Troubleshooting Import Image 2 Lotus Notes (II2LN) agents on Domino servers
Category Import Image 2 Lotus Notes
This article will teach you how to get Import Image 2 Lotus Notes (II2LN) agents running on your Lotus Domino server
This article will teach you how to get Import Image 2 Lotus Notes (II2LN) agents running on your Lotus Domino server
II2LN can
run both on Notes clients and on Domino servers. The ability to run II2LN
on a server is convenient for reasons such as;
- You want to use II2LN in your web applications, hosted on your Domino server.
- You don't want to install II2LN locally on each Notes client for your Notes applications. Central administration of II2LN is ensured
- You want to be able to process images at non-peak hours
- You want to batch process huge numbers of images, without locking the users Notes clients for hours
- You don't want to lock your Notes applications
and forcing users to be logged on to process images.
Below you find a birds-view point-by-point list on what to check in order to get II2LN agents running on a server;
- Install II2LN on the server. Pay extra
attention to the installation if you have multiple Domino server
installations on a single server ("partitioned servers") or if
you have one or more Notes clients installed on the server. The later was
very common some years ago, in order to have a Notes client to perform
administration tasks when working on the server. These days, that need
is completely gone, as we can do all our administration tasks from the
Notes Administrator-client. If you fall into the "old" category
( :-)) and do have a Notes client on the server, you must refer to the
User's Guide found on the II2LN
homepage. The technical reason
for this is that the II2LN components must be installed into specific directories
in order to work.
- If you have a server- or site license
for II2LN, install that too on the server. The license is delivered as
a .reg file and you should verify that it contains two registry hive settings,
such as;
REGEDIT4
[HKEY_CURRENT_USER\Software\Voith's CODE\Import Image 2 Lotus Notes]
"Key"="Bla bla super long key here"
[HKEY_USERS\.DEFAULT\Software\Voith's CODE\Import Image 2 Lotus Notes]
"Key"="Bla bla super long key here"
The reason for this is that the first registration key will install the license to the current session, while the second registration key will install the key to the default session, meaning that also that Domino servers running as a NTSERVICE, will pick up the license correctly.
Remember that II2LN can run on the server without a license, but then all images will be watermarked with the Voith's CODE logo.
- If you have installed the II2LN on the
server, and/or installed the license for the first time, please reboot
the server. The reason for this is so the Domino server picks up the correct
path settings, and optionally also picks up the license, no matter how
the Domino server has been installed. For the really technically savvy
Domino administrator, there are ways to avoid a complete reboot,
but you really have to know how to stop and restart services and so forth
in order to pick up environment settings. It is just easier (and often
much quicker) to reboot the server!
- Create a test database on the server.
The idea is to have a database which runs an agent on the server
in order to report back to you whether the II2LN was successful or
not.
- You can name the agent anything you
want, in my sample I have called it "Verify II2LN installation on
the server".
Ensure that the agent is running on a schedule, and click that Schedule-button to set the server-name;
Set a schedule you feel comfortable with... and do remember to turn off the agent after you have received your information! You don't want to waste server cycles on a spinning non-important agent!!!
- Now, you must set the agent's Runtime
Security Level, to level 2 or 3. For example;
This is very important, as you agent will need to access the server's local file system in order to load the II2LN DLL file. Without the setting above, your server log will contain entries like this;
01.10.2009 13:15:13 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN: INITIALIZE error: 201 Operation is disallowed in this session, (line # 9) in sub/function 'INITIALIZE'
Also note. You have to have high enough rights on your server to set this option in an agent. If you - or your Domino Administrator, verify whether your current user id is specified in the server document's Security-field "Sign or run restricted LotusScript/Java agents";
Your user id must either be explicitly be specified here, or you must be a member of one of the groups specified in this field. By the way; the user id you are working with right now, is the so-called signer id of the agent. Often corporations have separate so-called agent signer ids, which has the sole purpose of signing trusted agents and databases within your organization. Hereby highly advised to use agent signer ids!
- Enter some LotusScript code to your
agent (I have attached the complete agent at the end of this article if
you don't want to type!). The (Options)
section should contain these lines;
Option Public
Option Explicit
%REM
This agent will try to load the II2LN DLL and use it's 4 identification function. If this doesn't work, you know
something is wrong with the II2LN installation on the server!
http://www.vcode.no/ii2ln
%END REM
- The (Declarations)
section contain the lines which declare the functions to use in the II2LN
DLL. Those lines are the actual connection between LotusScript and II2LN
DLL when the agent is run. By the way, not how the DLL is just specified
as "VCII2LN.DLL". This means that Domino will find the VCII2LN.DLL
in a directory specified by the system environment variable PATH on your
server (do you now see why we have to reboot the server?). You could
specify a full path here to the VCII2LN.DLL, but then you must
be very specific about other installation issues. Refer to the User's Guide
if interested! Below you see the Declarations lines;
Declare Function GetII2LNMajorVersion Lib "VCII2LN.DLL" () As Integer
Declare Function GetII2LNMinorVersion Lib "VCII2LN.DLL" () As Integer
Declare Function GetII2LNBuildNumber Lib "VCII2LN.DLL" () As Integer
Declare Function GetII2LNVersion Lib "VCII2LN.DLL" (_
Byval strOutBuf As String, _
Byval iLenOfOutBuf As Integer) As Integer
- Now it's time to enter the real code
in the Initialize-section. The lines look like this and hopefully they
are pretty self-explanatory;
' The first and foremost check is whether the II2LN DLL will load at all. I use standard LotusScript exception handling
' to catch this issue
On Error Goto ErrorHandler
Dim iMajorVersion As Integer
iMajorVersion = GetII2LNMajorVersion()
Print "Yiiha, II2LN *is* installed on the server! The Major Version is " & Cstr( iMajorVersion)
Dim iMinorVersion As Integer
iMinorVersion = GetII2LNMinorVersion()
Print "II2LN Minor Version is " & Cstr(iMinorVersion)
Dim iBuildNumber As Integer
iBuildNumber = GetII2LNBuildNumber()
Print "II2LN Build Number is " & Cstr(iBuildNumber)
Dim strVersionBuf As String * 255 ' Make a string large enough for the version string
Dim strTmp As String
Dim iLenOfReturnedBuf As Integer ' Hold the length of the returned buffer
iLenOfReturnedBuf = GetII2LNVersion(strVersionBuf, 255)
strTmp = Left$(strVersionBuf, iLenOfReturnedBuf) ' Strip of trailing blanks
Print "II2LN Complete Build String is " & strTmp & ". II2LN seems to be working fine!"
Exit Sub
ErrorHandler:
Dim strErrMsg As String
strErrMsg = |II2LN: | & Getthreadinfo(1) & " error: " & Err & " " & Error(Err) & ", (line # " & Erl & ") in sub/function '" & Lsi_info(2) & "'"
Print strErrMsg
Exit Sub
- Save the agent and enable it on the
server. Note that this agent only use Print-statements to report back to
you. On a Domino server, print-statements end up in the servers log database.
You you can just wait.
If you take a look on the agent's log from time to time (right click on the agents name, within the Lotus Designer), you can see whether it has run or not.
If the agent hasn't run yet, you will see this message;
And if it has run, it will look something like this!
This means its time to head over to the servers log database (typically named log.nsf in the root directory of your server)
- Open the log-database on the server
(again, you must probably have enough rights to access this database).
If you can't see the results, then ask your Domino Administrator to look
for you;
The response will be in the Miscellaneous Events view.
- The log will contain entries like the
ones below if your II2LN is successful!
01.10.2009 14:24:21 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: Yiiha, II2LN *is* installed on the server! The Major Version is 1
01.10.2009 14:24:21 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Minor Version is 6
01.10.2009 14:24:21 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Build Number is 0
01.10.2009 14:24:21 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Complete Build String is 1.6.0.0. II2LN seems to be working fine!
If you have a problem with the II2LN installation, the exception handler in the LotusScript code above will kick in and show you a message similar to this;
01.10.2009 14:29:13 AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN: INITIALIZE error: 48 Error in loading DLL, (line # 9) in sub/function 'INITIALIZE'
- Hey, I have don't all the stuff above,
but still the images won't process!!!! First, take a look at the always
present log field VCII2LN_Log in the processed documents.
If you see some error message such as;
ERROR: Current document analyse: Error during DXL processing. Message from DXL processor are 'A user name must be specified for applications running on a Domino server'.
This means that we need to use the ImpersonateAs import option too. You could for example use your server's name in the format CN=MyServerName/O=MyOrganizationName.
Hopefully you now have a fully working II2LN installation on your server!
Please find the complete agent attached too here!
