How to backup the messages in the LN2TC database to troubleshoot problems with TCLINK-LN
I use the Kofax Communication Server TC/LINK-LN (Link for IBM/HCL Notes) and I face one of the following issues:
- Messages sent from IBM/HCL Notes are ending up in the LN2TC.NSF mail router database, but they are not picked up from there by TC/LINK-LN
- The layout of messages in KCS as shown for example in the image preview of the KCS Client is not as you expect it (message parts are missing, different font,...)
- This knowledge base article gives some hints to troubleshoot problems when sending from IBM/HCL Notes to KCS using TC/LINK-LN.
- It describes a technique to get a backup of those outbound messages waiting in the LN2TC mail router database, before they are picked up from there by TC/LINK-LN.
- This message backup can be used to verify/reproduce the problem in another test- or development environment, using exactly those messages as sent by the customer.
- The screenshots and menu options shown in this article assume that the IBM/HCL Notes client is configured to run in the so called "Basic mode" instead of running it in the "Eclipse mode", which is the default settting. Basic Mode is activated with the following option in the NOTES.INI file, which is typically located in the folder
C:\Program Files (x86)\IBM\Notes or C:\Program Files (x86)\HCL\Notes
Step 1: Preparations
- Login interactively (or via Remote desktop Admin mode) with the same Windows user as used by TC/LINK-LN
- Stop all instances of TC/LINK-LN running on different KCS Link Servers that are polling this specific LN2TC database.
- On one of the Link servers, start the Lotus Notes client (the Lotus Notes client cannot be started if TC/LINK-LN is still running). Typically, TC/LINK is runs with a Lotus Notes User-ID without password protection. If you start the Lotus Notes client now, it will use the same Lotus Notes user and therefore you shouldn't get a prompt to enter a password.
Step 2: Create a new local database, which will be used to backup the messages
- Within the IBM/HCL Notes client, use menu option File - Application - New...
- In the Server field, leave the default Local
- Select a Title (e.g. LN2TC Backup) and
- a File name for where the new database should be stored (e.g. C:\Temp\LN2TC_Backup.nsf).
It is recommended to use the Browse button, showing the folder icon near the File name edit box, to be sure that an existing directory is used.
- Enable the check-box Show advanced templates and select the Mail router mailbox (xx) from the list (xx is a numeric value and depends on the installed version of the Client, it is e.g. 11 if HCL Notes client version 11 is installed)
- Then press the Encryption... button and select in the next dialog the radio button Do not locally encrypt this database
NOTE: If you forget to configure the correct Encryption mode, you will not be able to open the database with the IBM/HCL Notes client of your Test/Development environment (Step 11). You will get an error message stating:
- Confirm both dialogs with OK and the database will be created (check with Windows Explorer).
- After pressing OK, a new tab window will be opened showing About LN2TC Backup - Design
- Close this tab and it will show you the newly created database without any documents inside.
Step 3: Send some problem messages
- Now send some of the problematic messages (from the IBM/HCL Notes client or any other source, e.g. internet messages received via the Notes SMTP connector).
These messages will end up in the LN2TC database.
- From there they will not be picked up anymore because all TC/LINK-LN instances are stopped.
- If there already are problem messages located in the LN2TC database, which could not be picked up by TC/LINK-LN, you can skip this step.
Step 4: Open the LN2TC database located on the Domino Server
- Check the file name of the mail router database used by TC/LINK-LN with the registry editor (regedit.exe), typically this is LN2TC.NSF
Registry value: HKLM\SOFTWARE\WOW6432Node\TOPCALL\TCLINKLN\NOTES\Database
- Within the Lotus Notes client use the menu option File - Application - Open...
- A new dialog opens, in the Look in... drop-down box select the correct Domino Server.
- The Name of the Domino Server can also be seen in the TC/LINKLN registry under registry value
- In the Edit box File name enter the name of the database as specified in registry value
Typically this will be LN2TC.NSF
- Once you selected the correct values, press the Open button
- If the LN2TC database was opened the first time, you will again get a About using this database tab, which can be closed with the x in the tab.
- Afterwards you will see the database. Inside the database you see the messages sent in Step 3 and possibly also other messages which have been sent by the customer in the meantime.
- You can use the menu option View - Refresh or the F9 key refresh the view.
Step 5: Copy the problematic documents from the LN2TC database
- Now you should select the problem-documents in the view. To do so set a check-mark into the left-most column of the view (click in-there using the mouse), see area marked in red in the next screen shot.
- To select ALL documents you can also press the keys Ctrl-A
- Now copy the selected documents to the clipboard using Ctrl-C. If you selected many or large messages you will see a progress bar. Wait until all messages are copied.
- Click on the LN2TC Backup tab to navigate to the backup database.
- Press Ctrl-V to paste the selected documents to this database. After finishing this step you'll have a backup copy of the documents within the LN2TC_Backup.nsf database.
Step 6: Also get a copy of the TCSETUP.NSF
- The setup database contains important configuration data, e.g. the design of special forms. For reproducing problems it is therefore important to also get a copy of this database.
- Verify the used database name in the registry of the TC/LINK-LN, typically this will be TCSetup.nsf
Registry value: HKLM\SOFTWARE\WOW6432Node\TOPCALL\TCLINKLN\NOTES\TCSetupName
- Open the database in the IBM/HCL Notes Client using menu option File - Application - Open
Again the correct domino server name must be selected using the Look in drop-down box:
- Create a copy of the TCSetup.nsf database in the IBM/HCL Notes client using menu option File - Application - New Copy...
- Use the server Local
- Within the File name we recommend to use the same directory as used for the LN2TC_Backup.nsf. Use TCSetup.nsf as file name.
- Uncheck the check-box Access Control List
- Select the radio button Application design and documents (this is the default selection)
- Press the button Encryption and select the option Do not locally encrypt this database in the next sub-dialog. Confirm with OK
- After pressing OK you will get a copy of the TCSetup.nsf in the C:\Temp folder
Step 7: Version of installed Lotus Notes client
- For analyzing the problem it is also important to know the exact version of the Lotus Notes client currently installed on your KCS Link server.
- Within the IBM/HCL Notes client select menu option Help - About Notes. Add a screenshot of the version, which also shows the installed fix pack.
- In general we recommend to use the latest version / Fixpack the Notes client.
Step 8: Prepare necessary TC/LINK-LN trace settings
- Now configure appropriate Trace settings in the registry of TC/LINK-LN.
HKLM\SOFTWARE\WOW6432Node\TOPCALL\TCLINKLN\MaxTraceFiles >= 10
HKLM\SOFTWARE\WOW6432Node\TOPCALL\TCLINKLN\MaxTraceFileSize >= 10000
- Delete existing TCLINKLN*.TRC files in the directory C:\TCOSS\Trace
Step 9: Process the messages with TC/LINK-LN
- Close the IBM/HCL Notes client.
- Start the TC/LINK-LN using KCS Monitor. Only one instance of TC/LINK-LN should be started. Other instances of TC/LINK-LN installed on other KCS Link servers should be kept in status: 'stopped'. By doing so it is ensured that all messages are processed on this TC/LINK-LN instance and the resulting traces will contain all messages.
- Wait until all messages are processed (check the message counter in KCS Monitor and use TCFW).
Step 10: Collect all trace information:
- Collect the following information and analyze the problem (see step 11) or forward them to your next level of support.
- Database backups C:\Temp\LN2TC_Backup.nsf and C:\Temp\TCSetup.nsf
- Registry backup of registry sub-key HKLM\SOFTWARE\WOW6432Node\TOPCALL (as .reg file)
- TCLINKLN Traces (C:\TCOSS\Trace\TCLINKLN*.Trc)
- Screenshot of used Lotus Notes client version.
Step 11: Verify the problem in a test- or development environment
- To verify the problem in a test- or development environment the steps are reversed.
- The LN2TC_Backup.nsf must be copied to the Test- or development server where TC/LINK-LN is installed
- TC/LINK-LN must be stopped and the local LN2TC_Backup.nsf database is opened in the IBM/HCL Notes client
- The messages in the LN2TC_Backup.nsf database have to be checked to find out which addressing was used (domain names, recipients,...)
- Depending on the used addressing, some registry values in the test environment have to be adapted to match the addressing of the test messages,...
- the registry value HKLM\SOFTWARE\WOW6432Node\TOPCALL\TCLINKLN\NOTES\Owndomain must be adapted and
- appropriate Services/users must be created in KCS
- The problem documents are selected in the LN2TC_Backup.nsf with a tick mark and copied to the clipboard with Ctrl-C
- Then the LN2TC Database on the Domino Server is opened in the test environment and the documents are copied over using Ctrl-V.
- Afterwards TC/LINK-LN is started to process the messages which have been manually copied to the LN2TC database
Level of Complexity
|Kofax Communication Server
|10.0 or higher||IBM Notes Client 9.0.1 FP8 or higher
HCL Notes Client 11.0 or higher
Notes, HCL, IBM, Lotus, troubleshooting, message, stuck, nsf, LN2TC, TCSetup, database, flow, conversion, error
Article # 3035034