Skip to main content
Kofax

How to set up correct tracing for SAP related KCS Links (TC/LINK-SC, TC/LINK-SC7)

Summary

5259

Description:

  • My customer encountered some problems between SAP and KCS (TC/LINK-SC or TC/LINK-SC7).
  • Which information must be gathered to troubleshoot the problems?
  • Which traces must be enabled and how are these trace files saved for further analysis by the next level of support?

Solution:

  1. General Troubleshooting guidelines:
    • Collect some more details of the problem: Is the problem specific to some messages, for example:
      • Messages sent from a specific SAP application (e.g. order processing).
      • In this case check if the problem occurs also when sending a message from 'SAP Office'.
        • Messages with a specific message output format (Postscript, PCL, PDF). Messages sent by a specific user.
        • Messages sent to specific recipients (e.g. all FAX messages to Australia). Messages containing multiple recipients.
    • Is the problem reproducible?
      Check if the problem is reproducible or not. If a problem is reproducible it is easier to activate full/high traces and to capture the issue in them. If you are operating in fault tolerant / load balancing mode (multiple TC/Link instances polling the same SAP client), start only one instance of TC/Link and stop all the others connected to the same SAP client. This will ensure that the traces of the remaining running instance contain all relevant information.
    • Ensure to get consistent traces:
      Traces captured on different locations (SAP Server, KCS Link Server) must cover the same time period. It is difficult or even not possible to analyze a problem if the traces taken on SAP side cover a different time period and therefore also different messages than the traces taken on KCS TC/Link side. Therefore all information, collected for a specific problem, (TCLINKSC/SC7 Traces, SAPConnect Traces, dev_icm traces, RFC Traces, Event log backups, registry backups, SAPRFC.INI settings,....) must be taken from the same time stamp and should cover the same time period.
    • Ensure that the trace contains problematic documents:
      Verify that the problem you encountered is really part of the traces, e.g. by checking the time period covered by the traces and setting the number of trace files large enough.
      Get some more details about the problematic documents (e.g. message subject, recipient number, when sent exactly) to make it easier to identify them within the traces.
    • Ensure that the Trace covers the complete message flow (original message + Notification):
      If the problem is a wrong or missing status update in SAP (send orders, which are already completed are still shown as 'in transit') it is important that you capture the traces of a complete message transfer. So the traces should cover both the original outbound message (SAP to KCS) and the corresponding notification sent back from KCS to SAP.
  2. Trace settings for TC/LINK-SC7 (SMTP communication) and TC/LINK-SC (RFC communication)
    • Configure the following trace settings for TC/LINK-SC(7) using regedit:
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\MaxTraceFiles >= 10
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\MaxTraceFileSize >= 10000
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\AppendTrace=1
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\General\TraceLevel=0xFF
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\General\MailDebug=1
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\General\TraceSmall=1
          HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\TOPCALL\TCSIDebug=1
    • If your problem is somehow related to the generated message output (e.g. Fonts not shown correctly, characters are replaced by # or other characters, garbled output, wrong margins, document conversion problems reported on the TC/Link, ...) it is additionally necessary that the TC/Link traces contain a complete message dump of the messages. This is done by setting the following registry value:
      HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\General\TraceSmall=0
    • For TC/LINK-SC7 it is important to also trace the SMTP communication with the SAP server. Additionally set the registry value...
      HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\TCLSM\TCPDebug=1
    • For TC/LINK-SC it is important to additionally trace the RFC communication with the SAP server. Additionally set the registry value...
      HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\SAP\TraceLevel=7

Notes:

  • <LinkInstanceName> has to be replaced by the correct instance name, typically TCLINKSC7 or TCLINKSC. On 64-Bit machines the registry setting can be found in the registry sub-key HKLM\SOFTWARE\Wow6432Node\TOPCALL\<LinkInstanceName>.
  • After changing the trace levels, the TC/Link instance must be restarted.
  • Check if the available disk space is large enough to hold the configured number of trace files with the configured size.
  • If the problem is reproducible, existing trace files should be deleted/moved before reproducing the problem.
  • Trace files can be found here: C:\TCOSS\Trace\<LinkInstanceName>*.trc, e.g.
    C:\TCOSS\Trace\TCLINKSC7*.trc
  1. Some basics to operate with the SAP Client / Sending a message with the SAP client 
    • SAP Transactions codes:
      • SAP transaction codes are used to navigate to different areas within the SAP Client user interface.
      • They are entered into the SAP transaction code edit box of the SAP Client as shown in the screenshot below.
      • The SAP Client stores a history of the used transaction codes and you will find an already used transaction code if you open the drop down list.
        Screen Shot 2018-07-25 at 3.03.59 PM.png
      • SAP Transaction codes are case-insensitive, but they depend on the context, e.g. if you are currently in the SAP Connect administration you cannot directly enter the transaction code 'SO02' to change to the SAP Office outbox.
      • But if you precede the transaction code with /n, navigation starts from the 'root-node', you can enter '/nso02' to go directly to the SAP Connect outbox.
    • Sending a message using SAPOffice:
      • A message can be sent from the SAP Client within the transaction '/nso02' (SAP Office outbox).
      • Use the 'New message' button in the toolbar.
      • FAX addresses must be entered with a leading 2-character country code (e.g. AT for Austria) followed by the FAX number (city code + local number), e.g. AT18664555383.
      • SAP recognizes, based on the addressing syntax, whether a recipient is a FAX recipient or an e-mail recipient (recognized with the @ character)
        Screen Shot 2018-07-25 at 3.12.03 PM.png
        • In the 'Trans options' of the recipient section you can configure whether you want to get back notifications. Leave it on the default 'Confirm Send status' = 'Always'.
          Screen_Shot_2018-07-25_at_3.16.49_PM.png
        • The messages are not sent immediately. A 'Send job' exists, which runs in periodic intervals (typically every 1..15 minutes) and transfers the messages.
        • This 'Send job' can also be triggered manually (Transaction code /nscot, menu option 'Utilities' - 'Start send process').
  2. Checking the status for messages in SAP: SAP Transactions SOST/SOIN
    • Outbound requests: Transaction SOST
      • SAP itself provides a list of all messages and their current status.
      • This list can be shown by calling the transaction code '/nsost'.
      • You can apply different filters within this list, e.g. to show only messages which reported an error or filters based on a specified time period.Screen Shot 2018-07-25 at 3.19.47 PM.png
      • Meaning of the status symbols and of the Msg Numbers:
        • If the status symbol is shown green (Msg=701): indicates a successful transmission. The delivery notification was returned successfully to SAP.
        • If the status symbol is shown red (Msg=812): indicates a transmission error. Either SAP failed to deliver the message to the next node or it is set to failed because KCS returned a non-delivery notification (e.g. because of a wrong FAX number).
        • If the status symbol is shown as a grey diamond (Msg=718): indicates that the message has been forwarded to the TC/Link but that no final notification has been received yet. If the status symbol remains in this status, even after the FAX has been sent successfully, it indicates a problem with the SOST status update.
      • Getting more detailed information.
        • If you click the numeric error code in the 'Msg' column it will show you a descriptive text in a new dialog window.
        • If you push the button 'Long text' in this dialog, it will open another new window which gives you even more information, e.g. here you can see the 2-character error code and the corresponding error description reported by KCS.
          Screen Shot 2018-07-25 at 3.21.30 PM.png
      • Additional functions available for the messages shown in SOST.
        There are some more interesting buttons shown in the toolbar:
        Screen Shot 2018-07-25 at 3.28.14 PM.png
        • The 'Trace' button (green border) will show you the outbound SAP Connect Trace (SAPConnect Traces are explained below).
        • The 'Transmission history' button: (red border) shows you a list of status changes (when was the message transferred to TC/Link, when was the Notification received).
        • The 'Display Document' button (blue border) opens the document itself. In the document you can navigate to the 'Recipient list' tab and you will also see the transmission history.
          Screen Shot 2018-07-25 at 3.29.31 PM.png

Inbound SMTP requests: Transaction SOIN

  • When using SMTP based communication with TC/LINK-SC7, the inbound messages and notifications returned from KCS to SAP can be seen by using the transaction code '/nsoin'. Here you will also find for example the 'Trace' button in the toolbar. This directly leads you to the SAPConnect Notification trace for this specific inbound message / notification.
    Screen Shot 2018-07-25 at 3.32.02 PM.png
  1. SAPConnect Trace
    • The SAP-Connect trace is the most important trace on SAP side for troubleshooting problems with KCS.
    • It shows all relevant actions performed for a specific message, e.g. format conversions on SAP side, recipient mapping,....
    • The SAPConnect Trace can be activated for SMTP based (TC/Link-SC7) or RFC-based (TC/Link-SC) communications, but there is one major difference:
      • For the RFC-based communication, used by TC/LINK-SC, the entire communication of one message is stored in one trace. So one traceID contains the original outbound message and the appropriate Notification.
      • For the SMTP based communication as used by TC/LINK-SC7, the SAPConnect Trace of the outbound message (SAP to KCS) and the appropriate trace of the notification returned from KCS back to SAP, are stored in different traces. The trace for the outbound message contains the original subject of the message as generated in SAP while the notification trace is additionally prefixed with the subject configured within the Notification covers (registry values HKLM\SOFTWARE\TOPCALL\
      • <LinkInstance>\TOPCALL\DelCover and NonDelCover), typically 'KCS delivery notification' or 'Delivery Failure' is used. So the notification trace shows then, for example, 'KCS delivery notification: ' followed by the original subject.
    • How to enable the SAPConnect trace?
      • Transaction /nSCOT, menu option 'Utilities' - 'Trace Settings'.
      • Set all options to 'Activated'.
        Screen Shot 2018-07-25 at 3.34.10 PM.png
      • Send a problematic message and wait until the notification is returned from KCS to SAP.
    • How to check and save the SAPConnect Trace?
      • After sending the message you should be able to locate the SAPConnect Trace files:
      • Transaction /nSCOT, menu option 'Utilities' - 'Trace selection'.
      • You can define different filter settings, by default the current date is inserted as filter.Screen Shot 2018-07-25 at 3.35.05 PM.png
      • Once the filter settings are confirmed, you will see a list of all matching trace files. In the example below you see that there are 2 relevant traces:
      • TraceID 66157 is the original outbound message for a message sent from SAP via TC/Link-SC7.
      • TraceID 66158 is the appropriate Notification sent back from KCS to SAP via TC/Link-SC7.
      • You can export this list to a local file by using the menu option 'List - Export - Local file...'. Use the option 'Unconverted' to get a pure text file.Screen Shot 2018-07-25 at 3.36.17 PM.png
      • If you double-click the appropriate trace line, it will open the trace.
      • If SAP recognizes errors they are typically marked red within the trace file itself.
      • Export the trace file by using the menu options 'List - Export - Local file...' and choose the format 'Unconverted' to get a pure text formatScreen Shot 2018-07-25 at 3.36.57 PM.pngScreen Shot 2018-07-25 at 3.37.05 PM.png
      • Export the traces for the original outbound message and for the trace for the notification.
      • Choose self-explaining file names, e.g. 'OutboundMessage.txt' for the outbound message and 'Notification.txt' for the appropriate Notification.
      • See attached a sample trace for a successfully sent FAX message sent via TC/Link-SC7 (outbound message + Notification).
        SAPConnect-SC7-OutboundMessage.txt
        SAPConnect-SC7-Notification.txt
      • See attached a sample trace for a successfully sent FAX message sent via TC/Link-SC.
        SAPConnect-SC-Outbound+Notif.txt
    • What can be seen in the SAPConnect Trace?
    • SAPConnect traces give the most important information for analysing problems where the status update in
      SAP (transaction SOST) does not work correctly.
    • If the status update works correctly you should find the following trace lines within the SAPConnect trace.

|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |Communication ID: ADR37000000000158
                                  |

|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |Original Send Request:
E21DC8130D7ED0F18F87000C29A7F4E8                    |
|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |Found SOES ADR37000000000158 for
8664555383                                 |
|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |Structure: SOES

                                  |
|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |SOES updated

                                 |
|24.10.2012|12:47:21|SO_ASYNCHRON_STATUS_UPDATE|    |SOST updated

                                    |

  1. Add screenshots of the used SAP version
    • For analyzing problems it is also important to know the exact SAP Version used at customer site.
    • You can get this by using the menu option 'System' - 'Status'.
    • Then press the button with the magnifier icon just below 'Component version' and it will open an additional dialog.
    • Within this dialog the most important version is the version of the SAP BASIS module.
    • Add screenshots of this version info when reporting a problem to your next level of support.
      Screen Shot 2018-07-25 at 4.10.00 PM.png
  2. SAP Internet communication manager (ICM) Tracing (only for TC/Link-SC7)
    • In addition to the SAPConnect Traces, explained in the previous chapter, it is sometimes helpful to enable the 'SAP ICM traces'.
    • If the SAP ICM Tracelevel is configured to '3' (highest possible value), the trace files will also include hex dumps of the SMTP communication with the distant mail server (smart host or TC/Link-SC7 server).
    • In this way all SMTP related communication (outbound and inbound) will be logged.
    • In general the same information can also be retrieved when you enable the TCLSM\TCPDebug=1 within the TC/Link-SC7 registry, but ....
    • ...the ICM trace really traces the SMTP communication how SAP itself gets it, so if you have any relaying smart host between SAP and TC/Link-SC7 it might change the SMTP communication (e.g. because Delivery status notifications DSN's are not supported by this relaying smart host).
    • Additionally the ICM Trace also gives a lot of information about how SAP did process a specific message
    • How to enable the ICM Trace?
      • Call transaction code '/nsmicm' and select then the menu option 'Goto' - 'Trace Level' - 'Set'.
        Screen Shot 2018-07-25 at 4.19.46 PM.png
      • For debugging purpose select a Trace Level = 3, you will get the SMTP communication dumps only with this tracelevel.
      • As this level produces a lot of trace output, it should be reverted to the default value (1) after analyzing the problem.
      • Once the complete communication is done, you can save the ICM trace to a file.
    • How to check and save the ICM Trace?
      • Call Transaction code /nsmicm and select the menu option 'Goto' - 'Trace File' - 'Save Locally'.
      • It opens a File - Save dialog, suggests a default file name, e.g. 'dev_icm.txt'.
      • For analysis you can open the file in anormal editor like Notepad.
      • If possible, use an Editor which is capable to display a list of search results. Notepad++ is a free alternative to Notepad.
      • Search for the string 'Address Offset' (there are 4 blank characters between the 2 words, it is important to enter the correct number of blanks!).
      • The search result will present you with the header lines. The next lines below show the hexdump of the SMTP communication.
      • If the trace line additionally contains 'IcmWriteToConn' it indicates outbound traffic (SAP to mailhost or TC/Link-SC7).
      • If the trace line additionally contains 'IcmReadFromConn received' it indicates inbound traffic (mailhost or TC/Link-SC7 to SAP).
      • In this way you should be able to find the outbound message by checking the 'MAIL FROM:' and the 'RECP TO:' SMTP commands:
      • Especially check the 'RCPT TO:' command in the outbound message, it must contain the string: 'NOTIFY=SUCCESS,FAILURE'.
      • If the string 'NOTIFY=SUCCESS,FAILURE' is missing, SAP does not request a notification from TC/LINK-SC7 and therefore also the status update in SOST will not work.

[Thr 3468] Address    Offset  IcmWriteToConn:
[Thr 3468] -----------------------------------------------------------------------
-
[Thr 3468] 009DF1C8  000000  52435054 20544f3a 3c464158 3d2b3433 |RCPT TO:
<FAX=+43|
[Thr 3468] 009DF1D8  000016  31383636 34353535 33383340 5343372e
|18664555383@SC7.|
[Thr 3468] 009DF1E8  000032  53422e4c 4f43414c 3e204e4f 54494659 |SB.LOCAL>
NOTIFY|
[Thr 3468] 009DF1F8  000048  3d535543 43455353 2c464149 4c555245
|=SUCCESS,FAILURE|
[Thr 3468] 009DF208  000064  204f5243 50543d72 66633832 323b4641 |
ORCPT=rfc822;FA|
[Thr 3468] 009DF218  000080  582b3344 2b324234 33313836 36343535
|X+3D+2B431866455|
[Thr 3468] 009DF228  000096  35333833 40534337 2e53422e 4c4f4341
|5383@SC7.SB.LOCA|
[Thr 3468] 009DF238  000112  4c0d0a                              |L..
|
[Thr 3468] -----------------------------------------------------------------------
-

  1. RFC Traces for the TC/LINK-SC (only for TC/Link-SC)
    • In some cases (e.g. if the authentication with the RFC user fails), it makes sense to also activate native RFC traces.
    • These traces log the RFC communication between TC/Link-SC and SAP Server.
    • The tracefiles are named 'rfc*.trc' and 'dev_rfc.trc' and they are located in the C:\TCOSS\TCLP folder of the KCS Link server.
    • If the problem is reproducible, delete the existing trace files before reproducing the problem again.

Please Note:

  • There is no automatic cyclic deletion of RFC Trace files and by default they are not limited in size.
  • So please be careful, leaving an installation with enabled RFC traces might fill up the hard disk and cause a whole series of other problems.
  • This is the reason why RFC Traces should only be enabled when explicitly requested by a support person.
  • RFC Traces should be disabled immediately after problem investigations are finished.

How to enable the RFC Traces?

  • RFC Traces are enabled within the C:\TCOSS\TCLP\SAPRFC.INI file.
  • For each TC/Link-SC instance there are 2 registry values defined:
    HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\SAP\RFCDestination
    HKLM\SOFTWARE\TOPCALL\<LinkInstanceName>\SAP\RFCR3Destination
  • These registry values contain strings, e.g. 'SRVTCLINKSC' and 'CLTCLINKSC'.
  • Each TC/Link-SC instance uses different strings, so these strings uniquely identify the TC/Link-SC instance. If you open the C:\TCOSS\TCLP\SAPRFC.INI file with Notepad, you will find for each of these string values a separate section, enclosed in square brackets, e.g.
    [SRVTCLINKSC] and [CLTCLINKSC]
  • In each of those [sections] you will find the entry
    RFC_TRACE=x
  • Set RFC_TRACE=0 to disable the RFC trace, or
  • Set RFC_TRACE=1 to enable the RFC Trace for this specific instance.
  • Due to the fact that each instance has a client- and a server-definition, the value must be changed two times for each instance.
  • Additionally you can also add the following setting in each [xxxx] section:
    RFC_MAX_TRACE=y

    where y is the maximum trace size in MB. Note that the number of trace files is not limited.
    After changing the RFC_TRACE settings in the SAPRFC.INI, the TC/Link-SC must be restarted.
  • Reproduce the problem and backup the C:\TCOSS\TCLP\rfc*.trc files and the C:\TCOSS\TCLP\dev_rfc.trc file together with the TC/Link-SC traces files.
  • Afterward testing disable the RFC_TRACE and restart the TC/Link-SC.
  1. Collect all available information
  • Finally collect all available information.
  • Verify that the collected information is complete and contains the problematic documents.
  • If you cannot locate the problem by yourself within the trace files, create a Support Case and add all information. Elevate the Case to the next level of Support.

    Here is again the list of the required information:
  • Description of the problem and how to reproduce it (if reproducible). Screenshot of the SAP version.
  • TC/Link-SC or TC/Link-SC7 traces containing the offending message(s) and the corresponding notification(s). SAPConnect Traces for message(s) and notification(s).
  • ICM Traces (only for TC/LINK-SC7).
  • Registry backup HKLM\SOFTWARE\TOPCALL or HKLM\SOFTWARE\Wow6432Node\TOPCALL (64-Bit machines) of the KCS Linkserver.
    Export the registry subkey in .reg format (not as text).
  • Installed version of KCS Package and a list of KCS hotfixes applied to the system. Installed version and language of the operating system including service pack level.
  • Application- and System Event log (exported in .evt or .evtx format).
  • C:\TCOSS\TCLP\SAPRFC.INI (only for TC/LINK-SC).
  • C:\TCOSS\TCLP\dev_rfc.trc and rfc*.trc files (if requested).
  1. Additional information

  • Knowledge base article: 'Troubleshooting SAP status update problems (SOST) when using TC/Link-SC7'.
  • SAP Note 1236270 - End of support for SAPconnect RFC interface.
    This SAP Note document shows the exact SAP 7.x version for which the SAP RFC interface is not supported anymore and therefore using TC/Link-SC7 is a must.
    Due to the fact that SAP OSS Notes can be viewed only by registered users, the Note has also been attached as .MHT file.
  • List of important SAP Transaction codes (also refer to the the TC/Link-SC and TC/Link-SC7 manuals):

SO01

SAP Office Inbox

SO02

SAP Office Outbox

SCOT

SAP Connect Administration

SOST

SAP Connect Transmission requests

SOIN

SAP Connect Inbound Send requests

SE16

Data browser, configuration tables

SU01

User administration

SMICM

SAP Internet communication manager settings and tracing

RZ10

SAP Profiles administration

SICF

Maintain services (Setup SAP SMTP server)

SA14

Pager service configuration

Applies To:

Keywords: SAP, RFC, notifications, notif, green, red,SC, SC&