In order to connect to a Domino Server or a Lotus Notes system, a discussion on what types of connections ("Session types" in Lotus Notes terminology) are possible, is appropriate. For these Connectors to operate, we will need to install a Domino/Lotus Notes client library, and the decision on which client library to install (also see Post Install Configuration) hinges on which Session Type is required.
A Notes client must be installed locally. This session type requires the Notes.jar file to be present in the TDI_install_dir/jars/3rdparty/IBM folder and that the local client binaries are specified in the PATH system environment variable.
The host parameter in the Notes API method for creating session must be null. A reference to the current server such as a null server parameter in the session creation method means the local Domino environment is indicated. If a Local Client session is to be created, the user parameter is also required to be null, which indicates to use the Notes user ID.
The local server is used only to create
a session. However, servers connected to the local environment can
still be accessed by specifying their names. The name is pointed as
first parameter of the getDatabase methods of the lotus.domino.Session class.
For Local Server sessions we need to install Lotus Domino
Server on the machine where TDI is installed. Also, the
path to this server installation must be added to the PATH system
environment variable.
When an IIOP session is specified the Connector uses a Domino User Name and the Internet password of this user for authentication. The users' User Name and Internet password are parameters of the Connector. It is not necessarily the same user as the system local user ID.
The IOR is a text string required by the Domino Java API in order to establish an IIOP session to the Domino Server. A client, like a Lotus Notes Connector, decodes the string IOR and uses it to establish the remote session. It is contained in a file, called diiop_ior.txt.
Any of the following changes could make the IOR string stale:
There are two approaches for the creation of an IIOP Session:
The TDI 6.0 Domino Change Detection Connector uses a session creation method which obtains the IOR string from the Domino HTTP task. In TDI 7.1 Domino/Lotus Connectors the parameter IOR String is externalized. This parameter is optional. If this parameter is missing or has no value, IIOP sessions will be created as they used to in TDI 6.0. If this parameter is present in the Connector configuration the following methods from the Domino Java API will be used for session creation:
static public Session createSessionWithIOR(String IOR, String user, String passwd) throws NotesException static public Session createSessionWithIOR(String IOR, String args[], String user, String passwd) throws NotesException
Providing this Connector parameter improves the Connectors in two ways:
When creating an IIOP session SSL could be used. The Connector first tries to retrieve the IOR String from the HTTP Task and then use the session creation method that accepts an array of strings as a parameter by providing the retrieved IOR instead of host parameter.
If SSL is used, the Connector tries to create a session using the following method:
static public Session createSessionWithIOR(String ior, String user, String passwd) throws NotesException
If SSL is not used, the Connector tries to create a session using the following method:
static public Session createSession(String host, String args[], String user, String password) throws NotesException
In this case the value of the HTTP Port parameter is appended to the host. This method tries to get the IOR string from the Domino HTTP task that should run on this port. The task must not use this port to run SSL on it.
These session types require ncso.jar file to be present in the TDI_install_dir/jars/3rdparty/IBM folder and that the local server binaries are specified in the PATH system environment variable.
Supported Sessions > | Local Client Session | Local Server Session | IIOP session |
Domino Change Detection Connector | Yes | No | Yes |
Domino Users Connector | Yes | Yes | Yes |
Lotus Notes Connector | Yes | Yes | Yes |
Domino AdminP Connector | No | Yes | Yes |
The Domino APIs for SSL are not JSSE compliant, and are instead Domino specific. This means that the TDI truststore and keystore do not play any part in SSL configuration for the Domino Change Detection Connector. For SSL configuration of the Domino Change Detection Connector, the TrustedCerts.class file that is generated every time the DIIOP process starts (in the Domino Server) must be in the classpath of TDI (ibmditk or ibmdisrv). You must copy the TrustedCerts.class to a local path included in the CLASSPATH or have the Lotus\Domino\Data\Domino\Java of your Domino installation in the CLASSPATH.
The file must be loaded by the same class loader that loads the ncso.jar file. As the ncso.jar file is loaded by the system class loader in TDI, the TrustedCerts.class file must be loaded by the system class loader. This can be easily done by dropping the TrustedCerts.class file in the "classes" folder; see "Classes" folder for more information.
32-bit Domino/Notes | 64-bit Domino* | |
32-bit JVM | Yes | No |
64-bit JVM | No | Yes |
Local Client and Local Server sessions use Lotus' Java API (Notes.jar). This Java API relies on the native libraries of the Notes/Domino installation (that is why have either a Notes Client or a Domino Server installed on the same machine as IBM TDI). Most modern operating systems allow a process to use either 32-bit or 64-bit native binaries but not both. If we use a 32-bit executable to start a process, that process can use only 32-bit native libraries.
On most 64-bit platforms it is possible to install and use 32 bit applications. If we want to use Local Server (Local Client) session to a 32-bit Domino Server (Notes Client) (even on a 64-bit operating system), we need to use IBM TDI with a 32-bit JVM.
The Domino/Notes Connectors are supported on Domino R8 and Domino R8.5 only.
There are a few configuration steps which must be performed after TDI has been installed so that the Lotus Notes/Domino Connectors can run.
Verify that the version of the Domino Server or Lotus Notes client (the Connector will be used with) is supported.
When a Connector is deployed on a Notes client machine these steps need to be performed only on the Notes client machine and not on the Domino Server machine to which the Notes client is connected.
When a Connector is deployed on a Domino Server machine these steps need to be performed on that Domino Server machine.
Lotus provides a Java library called Notes.jar, which provides interfaces to native calls that access the Domino Server (possibly through the network). It can be found in the folder where the Domino Server or the Lotus Notes client is installed (for example, C:\Lotus\Domino or C:\Lotus\Notes). Different settings must be performed depending on whether we create Local Client Session or Local Server Session, because the binaries differ between Lotus Domino and Lotus Notes.
-Djava.library.path="%PATH%"
CTGDJE010E Connector was unable to initialize local Notes session to Domino Server. Exception encountered: java.lang.Exception: Native call SECKFMSwitchToIDFile failed with error: code 259, 'File does not exist'You need to copy the Notes ID file intended for authentication to the Domino server in the Solution directory of TDI. Usually this file is located in the folder Notes_install_dir/Data/. The problem is caused by the way the notes.ini file points to the ID file. Instead of an absolute path a relative one is used (KeyFilename=user.id), so our components look for it in their current directory - the solution directory of TDI and not in the Data folder of the Notes installation.
-Djava.library.path="%PATH%"
Because of the way the Notes API is implemented, there can only exist one of two jars: either ncso.jar or Notes.jar in TDI_install_dir/jars/3rdparty/IBM. If both jars are present, then the behavior of the Connector is unpredictable.
CTGDJE010E Connector was unable to initialize local Notes session to Domino Server. Exception encountered: java.lang.Exception: Native call SECKFMSwitchToIDFile failed with error: code 259, 'File does not exist'You need to copy the Notes ID file intended for authentication to the Domino server in the Solution directory of TDI. Usually this file is located in the folder Notes_install_dir/Data/. The problem is caused by the way the notes.ini file points to the ID file. Instead of an absolute path a relative one is used (KeyFilename=user.id), so our components look for it in their current directory - TDI’s solution directory and not in the Data folder of the Notes installation.
When an AssemblyLine (containing Connectors) is executed by the TDI Server it runs in a single thread and it is only the AssemblyLine thread that accesses the AssemblyLine Connectors. The initialization of the Notes API, selecting entries, iterating through the entries and the termination of the Connector is performed by one worker thread.
A requirement of the Notes API is that when a local session is used each thread that executes Notes API functions must initialize the NotesThread object, before calling any Notes API functions. The Config Editor GUI threads do not initialize the NotesThread object and this causes a Notes exception.
There are several ways to initialize the NotesThread object. The way the Connectors do it is to call the NotesThread.sinitThread() method when a local session is created.
That is why the all Lotus Notes and Domino Connectors use their own internal thread to initialize the Notes runtime and to call all the Notes API functions. The internal thread is created and started on Connector initialization and is stopped when the Connector is terminated. The Connector delegates the execution of all native Notes API calls to this internal thread. The internal thread itself waits for and executes requests for native Notes API calls sent by other threads.
This implementation makes Connectors support the Config Editor GUI functionality and multithread access in general. The Lotus Notes Connector initializes the Notes runtime if a local session is created.
In order to use IIOP sessions, the TDI Lotus Notes/Domino components require the presence of the ncso.jar file.
From IBM TDI 6.1, ncso.jar will no longer be shipped with the TDI product. We need to manually provide this file in order for the TDI Lotus/Domino components to function properly.
However, the ncso.jar file is shipped with the Domino Server. This file can be taken from the Domino installation (usually <Domino_root>\Data\domino\java\ncso.jar on Windows platforms) and place it in the TDI_root\jars\3rdparty\IBM folder, so that the TDI Server will load it on initialization. Since the ncso.jar will not be provided as part of the IBM TDI 7.1 installation, some existing TDI 6.0 functionality will change as follows.
The TDI Server provides the "-v" command-line option which displays the versions of all TDI components. Since the ncso.jar file will not be provided as part of the TDI installation, if ncso.jar is not taken from the Domino server or Lotus Notes installation, messages like the following will be displayed (The components which do not rely on the ncso.jar have their versions displayed properly):
ibmdi.DominoUsersConnector: com.ibm.di.connector.dominoUsers.DominoUsersConnector: 2006-03-03: CTGDIS001E The version number of the Connector is undefined
The Server API provides a method to request version information about TDI components (Session.getServerInfo). If version information is requested via the Server API about any of the Connectors which rely on ncso.jar and if this jar is not taken from the Domino server or Lotus Notes installation, an error is thrown. For example if the local Server API is accessed through a script like this:
session.getServerInfo().getInstalledConnectors()
the following error is displayed:
18:16:12 CTGDKD258E Could not retrieve version info for class 'com.ibm.di.connector.DominoChangeDetectionConnector'.: java.lang.NoClassDefFoundError: lotus.domino.NotesException
AssemblyLines which use a Connector (which uses an IIOP session) will fail to execute with a NoClassDefFoundError exception, if the ncso.jar file is not taken from the Domino Server or Lotus Notes installation.
This is the table with the versions of all installed TDI components (available from the context-menu option Show Installed Components on a server visible in the Servers panel.) This table will fail to display component versions for any of the Notes/Domino Connectors if neither the Notes.jar nor the ncso.jar is taken from the Domino/Notes installation
The Insert new object box (activated by choosing Insert Component..., where available) will display all existing TDI Connector modes (not only the supported ones) for the Notes/Domino Connectors, if neither the Notes.jar nor the ncso.jar is taken from the Domino/Notes installation.
Attempting a connection to the data source from the Input Map tab for any of the Notes/Domino Connectors will display an error that the Connector could not be loaded, if the jar library is not taken from the Notes/Domino installation, whatever session is created.
This folder, located at TDI_Install_Folder/classes contains user-provided class files that are loaded by the system class loader. This folder can be used for specifying custom classes which must be loaded by the system class loader.
In order for a class file to be loaded by the system class loader, the class file needs to be copied to this folder. If the class is inside a Java package, then the class file must be put in the corresponding folder under the "classes" folder. For example, if a class file is contained in a Java package named com.ibm.di.classes, then the class file must be put inside the TDI_Install_Folder/classes/com/ibm/di/classes folder.
Only class files in the "classes" folder are loaded. That means that if a jar file is located in this folder, it will not be loaded at all. If the classes are packaged in a jar file, then these classes need to be extracted from the jar file into the "classes" folder.
The Domino Change Detection Connector enables IBM TDI 7.1 to detect when changes have occurred to a database maintained on a Lotus Domino server. The Domino Change Detection Connector retrieves changes that occur in a database (NSF file) on a Domino Server. It reports changed Domino documents so that other repositories can be synchronized with Lotus Domino.
Notes:
When running the Connector reports the object changes necessary to synchronize other repositories with a Domino database, regardless of whether these changes have occurred while the Connector has been offline or they are happening while it runs.
The Domino Change Detection Connector operates in Iterator mode, and reports document changes at the Entry level only.
On each AssemblyLine iteration the Domino Change Detection Connector delivers a single document object which has changed in the Domino database. The Connector delivers the changed Domino document objects as they are, with all their current items and also reports the type of object change - whether the document was added, modified or deleted. The Connector does not report which items have changed in this document or the type of item change. After the Connector retrieves a document change, it parses it and copies all the document items to a new Entry object as Entry Attributes. This Entry object is then returned by the Connector.
This connector supports Delta Tagging at the Entry level only.
This Connector can be used in conjunction with the IBM Password Synchronization plug-ins. For more information about installing and configuring the IBM Password Synchronization plug-ins, see the IBM TDI V7.1 Password Synchronization Plug-ins Guide.
The Connector stores locally, on the IBM TDI 7.1 machine, the state of the synchronization. When started it continues from the last synchronization point and reports all changes after this point, including these changes that happened while the Connector was offline.
Changed documents are not delivered in chronological order or in any other particular order, unless you check the "Deliver Sorted" checkbox in the configuration screen. Refer to Sorting for more information. Without using this option, it means that documents changed later can be delivered before documents changed earlier and vice versa.
The Connector will signal end of data and stop when there are no more changes to report. It can however be configured not to exit when all changes have been reported, but stay alive and repeatedly poll Domino for changes.
The Domino Change Detection Connector retrieves the Universal ID (UnID) of Domino documents. Use the UnID value to track document changes reported by the Connector.
For example, when a deleted document is reported, use its UnID value to lookup the object that has to be deleted in the repository you are synchronizing with. If you are synchronizing Domino users (Person documents), then you might need to find out when a user is renamed. When a user is renamed (the FullName item of the Person document is changed), the Connector will report this as a "modify" operation. When you lookup objects in the other repository by UnID, we will be able to find the original object, read its old FullName attribute, compare it against the new FullName value and determine that the user has been renamed.
Documents that are deleted from a Domino database can be tracked by "deletion stub" objects. Deletion stubs provide the Universal ID and Note ID of the deleted document, but nothing more. That is why when the Connector comes across a deleted document, it returns an Entry which does not contain any document items, but only the following Entry Attributes added by the Connector itself:
There is a parameter for each database called "Remove documents not modified in the last x days". Deletion stubs older than this value will be removed. If you are interested in processing deleted documents, synchronize (run the Connector) on intervals shorter than the value of this parameter.
On both Domino R8.0 and Domino R8.5, this parameter can be accessed from the Lotus Domino Administrator: open the database, then choose from the menu File -> Replication -> Options for this Application..., select Space Savers - the parameter is called Remove documents not modified in the last x days.
The default value of this parameter is 90 days.
UnIDs are the same across replicas of the same database. This allows you to switch to another replica of the Domino database in case the original database is corrupted or not available.
Document timestamps, however, are different for the different replicas. That is why when a switch to a replica is done, perform a full synchronization (use a new key for "Iterator State Key" and set the "Start At" parameter to "Start Of Data"). This will possibly report a lot of document additions and deletions which have already been applied to the other repository, but will guarantee that no updates are missed.
All items contained in a document are mapped to Entry Attributes with their original item names.
All date values are returned as java.util.Date objects.
The following Entry Attributes are added by the Connector itself (their values are not available as document items):
The Universal ID (UnID) is the value that uniquely identifies a Domino document. All replicas of the document have the same UnID and the UnID is not changed when the document is modified. This value should be used for tracking objects during synchronization. The Universal ID value is mapped to the $$UNID Attribute of Entry objects delivered by the Connector. The value of the $$UNID Attribute is a string of 32 characters, each one representing a hexadecimal digit (0-9, A-F).
The Connector also returns the NoteID document values. This value is unique only in the context of the current database (a replica of this document will in general have a different NoteID). The Connector delivers the NoteID through the $$NoteID Entry's Attribute. The value of this Attribute is a string containing up to 8 hexadecimal characters.
An Attribute named $$ChangeType is added to all Entries returned by the Domino Change Detection Connector.
The value of the $$ChangeType Attribute can be one of:
Several values are saved into the System Store and represent the current synchronization state. The Connector reads these values on startup and continues reporting changes from the right place.
Regardless of the mode in which the Connector is run two synchronization state values are stored in the User Property Store. These two values a stored in an Entry object as Attributes with the following names and meaning:
When the Connector is run, in addition to storing values in the User Property Store it creates (if not already created) a Connector-specific table in the System Store. The name of this table is the concatenation of "domch_" and the value of the Iterator State Key Connector parameter. This Connector-specific table stores values with the following characteristics:
The Connector-specific table is cleared each time the Connector successfully completes a synchronization session.
For each instance of the Domino Change Detection Connector executed on the same IBM TDI Server there is a different Connector-specific table in the System Store.
While the Connector is offline we can access the "since" datetime that will be used on the next Connector run. This datetime is stored in the User Property Store.
This is how we can get the datetime value for the next synchronization:
var syncTime = system.getPersistentObject("dcd_sync"); var sinceDateTimeAttribute = syncTime.getAttribute("SYNC_TIME"); var sinceDateTime = sinceDateTimeAttribute.getValue(0); if (sinceDateTime.getClass().getName().equals("java.util.Date")) { main.logmsg("Start date: " + sinceDateTime); } else { main.logmsg("Start date: Start Of Data"); }
"dcd_sync" is the value specified by the Iterator Store Key Connector parameter.
This is how we can set a start datetime for the next synchronization:
var syncTime = system.newEntry(); syncTime.setAttribute("SYNC_TIME", new java.util.Date()); //current time syncTime.setAttribute("SYNC_CHECK_DOCS", new java.lang.Boolean("false")); system.setPersistentObject("dcd_sync", syncTime);
No filtering of documents is performed in this version of the Connector. All database documents that have been created, modified or deleted are reported by the Connector.
If we need filtering do this yourself by scripting in the Connector hooks.
The changed documents can be delivered sorted by the date they were last modified on. This is done by checking the checkbox "Deliver Sorted" in the configuration screen.
Using sorting comes with a performance penalty, in terms of memory usage and CPU time. That is why we should consider carefully whether you really need sorting.
The Domino Change Detection Connector uses the timestamp of last modification for detecting changes in a Domino database. The Connector state includes timestamp values read by the Domino Server system clock. That is why changing the Domino Server system time while the Connector is running or between Connector runs might result in incorrect Connector operation - changes missed or repeated, incorrect change type reported, etc.
The Connector could need a bigger amount of physical memory - for example, when working on very large databases containing 1,000,000 documents or more, especially when performing a full synchronization. This is caused by the Connector keeping all retrieved document UnIDs in memory for the duration of the synchronization session. For example, 512 MB of physical memory should be enough for processing a database that contains about 1,000,000 changed documents (provided that no other memory consuming processes are running). If this amount of memory is unavailable, then we can increase the memory available to IBM TDI.
Also, be mindful of the "Deliver Sorted" parameter - enabling this could have a major performance impact.
The Domino Change Detection Connector supports two methods specific to it, as follows:
/** * This method saves the synchronization state of the Connector. * This method should be called by users (using script component) whenever * they want to save the synchronization state. * * @throws Exception if the synchronization fails. */ public void saveStateKey() throws Exception; /** * Skip the current document. Use this method to skip problem documents when * the Connector will otherwise die with an exception. * <p> * For example use the following script in the "Default On Error" hook of * the Connector: * * <pre> * thisConnector.connector.skipCurrentDocument(); * </pre> * * </p> * * * @throws Exception * If the Notes thread is not running or the Notes thread * encounters an error while processing the command. */ public void skipCurrentDocument()throws Exception;
See the section, Supported session types by Connector and the sections below about the issue of required libraries, and possible library conflicts.
The Connector requires that the following Domino Server tasks be started on the Domino Server:
If these Domino Server tasks are not started on the server the Connector will fail.
The Domino Change Detection Connector creates two sessions to the Domino Server - a session through the local Notes client code using the local User ID file and a remote IIOP session using an internet user account (the same Domino user can be used for establishing both sessions but this is not required). The accounts used for these sessions must have the following privileges:
We can configure this from the "Files" tab of the Lotus Domino Administrator: right click on the database which will be polled for changes, select "Access Control -> Manage...". If we don't see the user name associated with this User ID file listed, click the "Add..." button and add this user name to the list. Select this user name in the list and make sure that the Access is set to "Reader" or higher (that is, "Reader", "Author", "Editor", "Designer" or "Manager") for this user.
The Connector needs the username and password of a Lotus Domino Internet user for creating the IIOP session. The Internet user must have at least the "Reader" Access configured in the Access Control List (ACL) of the Domino database that is polled for changes.
You can configure this from the "Files" tab of the Lotus Domino Administrator: right click on the database which will be polled for changes, select "Access Control -> Manage...". If we don't see the Internet user listed, click the "Add..." button and add the Internet user to the list. Select the Internet user name in the list and make sure that the Access is set to "Reader" or higher (that is, "Reader", "Author", "Editor", "Designer" or "Manager") for this user.
The Domino Change Detection Connector provides the following parameters:
For Session Type=LocalClient, the following parameters are disregarded: IOR String, HTTP Port, Username and Use SSL.
The Delete button clears all synchronization state associated with the value of this parameter. When clicked, the Connector deletes the key-value pair from the User Property Store as well as the Connector-specific table from the System Store.
The default value is "Start Of Data".
This parameter is taken into account only when the persistent parameter specified by Iterator State Key is not found in the User Property Store.
It is only taken into account when the persistent parameter specified by "Iterator State Key" is blank or not found in the System Store and the "Start At" parameter is set to "Specific Date".
Solution: This exception indicates that the HTTP Web Server task on the Domino Server is not running. Start the HTTP Web Server task on the Domino Server you are trying to access and then start your AssemblyLine again.
Solution: This exception indicates that the DIIOP Server task on the Domino Server is not running. Start the DIIOP Server task on the Domino Server you are trying to access and then start your AssemblyLine again.
Another reason for this message is that the fully qualified host name of the Lotus Domino server is not correctly set (for example, it was left as localhost or 127.0.0.1). To solve this problem start "Domino Admin", open the server used, go to the Configuration tab and edit the "Server->Current Server document". In this document under the Basic tab add the correct value for "Fully qualified Internet host name", save the document and restart the server.
Solution: This exception indicates that the memory available to the IBM TDI Java Virtual Machine (the JVM maximum heap size) is insufficient. In general the Java Virtual Machine does not use all the available memory. We can increase the memory available to the IBM TDI JVM by following this procedure:
Edit ibmdisrv.bat in the IBM TDI install directory to adjust the existing -Xms16m option to -Xms254m -Xmx1024m in the next to last line of the file (that is, the line that invokes Java).
-Xms is the initial heap size in bytes and -Xmx is the maximum heap size in bytes. We can set these values according to our needs.
Solution: The user of the local User ID file is not given the necessary privileges on the database polled for changes. Give the necessary user rights as described in Required privileges.
If we run the TDI Server from the command prompt, then before this exception message is printed, a popup dialog box appears saying "This application has failed to start because nNOTES.dll was not found. Re-installing the application may fix this problem."
Solution: This exception message as well as the popup dialog box are displayed because the Connector is unable to locate the Lotus Notes dynamic-link libraries. Most probably the path to the Lotus Notes directory specified in ibmditk.bat or in ibmdisrv.bat is either incorrect or not specified at all. That is why we should verify that the Lotus Notes directory specified in the PATH environment variable in both ibmditk.bat and ibmdisrv.bat is correct. For more information please see Required Setup of the IBM TDI.
Solution: Override the "Default On Error" hook of the Connector. Use the skipCurrentDocument() method to increment the internal document counter of the Connector so that it skips the problem document. Also use the system.skipEntry() method to instruct the AssemblyLine to skip the current cycle - the Connector failed to read the document so it has no meaningful data to provide for this cycle.
The script that you put in the "Default On Error"hook should make difference between non-fatal errors (for example, document contains an invalid field) and fatal errors (for example, the Domino server is not running). You should not let the Connector continue iterating after a fatal error occurs. Here is a sample script for the "Default On Error" hook. The script skips only documents which contain an invalid date:
var ex = error.getObject("exception"); var goOn = false; if (ex != null) { if (ex.getMessage().indexOf("Invalid date") != -1) { goOn = true; } } if (goOn) { thisConnector.connector.skipCurrentDocument(); system.skipEntry(); } else { throw "Fatal error: "+error; }
java.lang.Exception: CTGDJE010E Connector was unable to initialize local Notes session to Domino Server. Exception encountered: java.lang.Exception: Native call SECKFMSwitchToIDFile failed with error: code 259, 'File does not exist'.Solution: Detailed information for this problem can be found in section Post Install Configuration, both in paragraphs "If we create Local Client Session" and "If we create IIOP Session".
Refer to the section on Supported session types by Connector on how this connector should be set up with the necessary libraries, and about interactions with other Domino/Lotus Notes Connectors.
Accessing Java Session Objects,
Accessing documents using Java classes.
The Domino Users Connector provides access to Lotus Domino user accounts and the means for managing them. With it, we can do the following actions:
Currently, the Connector does not support the process of Users recertifying.
The Domino Server accessed can be on a remote server, or on the local machine.
It operates in Iterator, Lookup, AddOnly, Update and Delete modes, and enables the following operations to be performed:
The Connector iterates through the Person documents of the 'Name and Address Book' database. All Person documents (matching the filter, if filter is set) are delivered as Entry objects, and all document items, except attachments, are transformed into Entry Attributes.
Along with the Attributes corresponding to the Person document items, the Entry returned by the Connector will contain some extra Attributes, created by the Connector itself. The table below describes these Attributes. Their names will be prefixed with "DER_" to indicate that they have been derived by the Connector, and they are not "native" Domino Attributes):
Attribute Name | Type | Value |
---|---|---|
DER_IsEnabled | Boolean |
true - if the user does not belong to a "Deny List only" group; |
In Lookup mode, the Connector will perform different type of searches, depending on the value of the Use full-text search parameter:
"Full-text search" will work both with full-text indexed and not full-text indexed databases; however, the search will be less efficient if the database is not full-text indexed.
It is also possible that the database full-text index will not be updated, in which case the search results would not match the actual database content.
This Connector can be used in conjunction with the IBM Password Synchronization plug-ins. For more information about installing and configuring the IBM Password Synchronization plug-ins, please see the IBM TDI V7.1 Password Synchronization Plug-ins Guide.
The Domino Users Connector requires Lotus Notes to be release 7.0 or 8.0; and Lotus Domino Server version 7.0 and 8.0.
Refer to the section, Supported session types by Connector for more information about required libraries setup, and possible library conflicts.
To authenticate the local server connection, Domino requires the user's short name and internet password (these are Connector's parameters).
The Connector needs the following parameters:
For Session Type=LocalClient, the following parameters are disregarded: IOR String, HTTP Port, Username and Use SSL. Also see Parameter migration from earlier versions for more information.
If this parameter is missing or empty, the local machine is used. This behavior ensures backward compatibility with pre-6.1 TDI configuration files.
"& Form = "Person""which limits the search to user documents only. The default value is empty.
TDI 7.1 introduces a Session Type parameter for this Connector, as part of a harmonization with the other Lotus Notes/Domino Connectors. The Session Type parameter covers functionality previously configured through the Authentication Mechanism parameter:
To have the IBM TDI access the Domino Server, you might have to enable it through...
The user account we have configured the IBM TDI to use must belong to a group listed under...
...and...
When the Domino Users Connector is running on a Notes client machine, there is communication going on between the Notes client machine and the Domino Server machine.
Port encryption in Domino and/or Notes can be used to encrypt this communication. Two options are available:
The Domino Users Connector impersonates as a Domino user in order to access the Domino Directory (Names and Address Book database).
The Domino Users Connector supports two authentication mechanisms - Internet Password authentication and Notes ID file based authentication.
The Domino Users Connector uses this mechanism in order to create an Internet Session object for making local calls based on the Domino Directory. This authentication mechanism requires that a Domino Server is installed on the local machine.
The currently configured default Notes ID file is a part of the Notes client configuration. Normally the Notes client stores the path to the currently configured default Notes ID file in the notes.ini file, so that when the next time Notes client starts it will use this Notes ID file by default.
The password of the Notes ID file must be supplied as a Connector configuration parameter Password.
The Domino Users Connector uses this authentication mechanism in order to create a Session object for making local calls based on the Notes user ID. A Domino server or Notes client must be installed locally.
This authentication mechanism can be used both on a Notes client machine and on a Domino Server machine. When this mechanism is used on a Domino Server machine the Server ID file is used. Normally Server ID files do not have passwords or have empty passwords; that is why you would normally leave the Password Connector configuration parameter blank. If, however, the Server ID file does have a password we should specify that password as the value for the Password Connector configuration parameter.
The Domino Server uses the Access Control Lists of the Domino Directory (Names and Address Book database) to verify that the Domino user which the Connector uses has actually the right to access the required database, document or field.
If the Connector is used to change the FirstName or LastName or both of a Domino user, then the Access Control Lists of databases to which the user used to have access before the renaming occurred must be updated manually, so that the new user name would be recognized.
The Connector iterates through the Person documents of the Name and Address Book database. All Person documents (matching the filter, if filter is set) are delivered as Entry objects, and all document items, except attachments, are transformed into Entry attributes.
Along with the attributes corresponding to the Person document items, the Entry returned by the Connector contains some extra (derived) attributes for which values are calculated by the Connector. Here is the list of the derived attributes:
In Lookup mode, the Connector performs searches for user documents, and the type of search depends on the value of the Use full-text search parameter:
When simple link criteria are used, we can use both canonical (CN=UserName/O=Org) and abbreviated (UserName/Org) name values to specify the user's FullName. The Connector automatically processes and converts the value you specified, if necessary.
When advanced link criteria is used, be careful and specify the user's FullName in the correct format, which is:
The AddOnly mode always adds a new Person document in the Name and Address Book database. The add process accepts whatever attributes are provided by the Attribute Mapping, however to have correct user processing by Domino, the attribute names must match the Item names Domino operates with. As the Connector operates with users only, it always sets the attributes Type and Form to the value of Person, thus overriding any values set to these attributes during the Attribute Mapping process. The LastName Domino user attribute is required for successful creation of a Person document. The HTTPPassword attribute is not required, but if present its value is automatically hashed by the Connector.
Depending on a fixed schema of attributes, the Connector can register the new user. The table below specifies these attributes and the Connector behavior according to their presence or absence in the conn Entry, and their values:
The attributes for which the Required for registration field is set to Yes are required for successful user registration. Along with these REG_ Attributes, the LastName Domino user attribute is also required for successful user registration.
If REG_Perform is set to true and any of the other attributes required for registration are missing, the Connector throws an Exception with a message explaining the problem.
In Update mode, the following happens:
When modifying a user, the Domino Users Connector always modifies its Person document in the Name and Address Book database with the attributes provided. The modify process accepts whatever Attributes are provided by the Attribute Mapping, however to have correct user processing by Domino, the Attribute names must match the Item names Domino operates with. See List of Domino user attributes (or Person document items) for a (possibly not full) list of Domino user properties.
As the Connector operates with users only, it does not modify the attributes Type and Form (their value must be Person) regardless of the Attribute Mapping process. If the HTTPPassword attribute is specified, its value is automatically hashed by the Connector.
In the process of modifying users, the Domino Users Connector provides the options to disable and enable users. A user is disabled by adding his name into a specified Deny List only group (consult the Domino documentation for information on Deny List only groups. Go to http://www.lotus.com/products/domdoc.nsf, and click the Lotus Domino Document Manager 3.5 link). A user is enabled by removing his name from all Deny List only groups.
The Connector performs user disabling or enabling depending on the presence in the conn Entry, and the values of the following Entry attributes:
The Connector can perform user registration on modify too. To determine whether or not to perform registration, the same rules apply as in the AddOnly mode. The same schema of attributes is used and all REG_ Attributes have the same meaning.
If the REG_ Attributes determine that registration is performed, the following cases might happen:
Notes:
For user deletion, the Connector uses the Domino Administration Process.
The Connector posts Delete in Address Book requests in the Administration Requests Database . Each request of type Delete in Address Book, when processed by the Domino Administration Process, triggers the whole chain of posting and processing administration requests and actions performed by the Administration Process to delete a user. The result of posting a Delete in Address Book administration request is the same as manually deleting a user through the Domino Administrator. In particular:
The Connector enables tuning of each single user deletion it initiates. The parameters that can be configured are:
The delete parameters described previous, have default values that can also be changed through APIs provided by the Domino Users Connector. Each time an instance of the Domino Users Connector is created (in particular on each AssemblyLine start), the parameters have the following default values:
If the default values fit the type of deletion we want, then no special configuration for the deletion is needed. You must specify the correct link criteria in the Delete Connector.
We can however use the APIs provided by the Domino Users Connector, to change these default values at runtime (using scripting):
The default values for the delete parameters are used in all deletions performed by the Connector, until another change in their values is made, or the Connector instance (object) is destroyed.
The following are possible scenarios that use these methods:
Another method to manipulate the delete parameters, is to provide the following attributes in the conn Entry:
If this attribute is missing in the conn Entry, the default value for Delete mail file is used.
If this attribute is provided in the conn Entry, its value determines the value for the Delete mail file parameter for the current deletion only:
If this attribute is missing in the conn Entry, the default value for Add to group is used.
If this attribute is provided in the conn Entry, its value determines the value for the Add to group parameter for the current deletion only:
The use of the DEL_DeleteMailFile and DEL_DeleteGroupName attributes in the conn Entry overrides the default values of the corresponding delete parameters for the current deletion only.
Setting the DEL_DeleteMailFile and DEL_DeleteGroupName attributes in the conn Entry can be done through scripting in the Before Delete hook. Adding attributes by scripting might not be very convenient, so you might prefer to use the default delete parameters values and the APIs that change them.
The following is a list (possibly not full) of Domino user document items, which are understood or processed by Domino when the server operates with users. For more information on these Items consult the Lotus Domino documentation. Go to http://www.lotus.com/products/domdoc.nsf, and click the Lotus Domino Document Manager 3.5 link.
The same names must be used for Entry attribute names when performing Add, Modify, Delete or Lookup operations with the Connector.
For Domino Users Connector with Domino Server for Unix/Linux, update the ibmditk and ibmdisrv scripts. Add the following two lines in the script, after the PATH definition and before the startup line:
LD_LIBRARY_PATH=Domino_binary_folder export LD_LIBRARY_PATH
where Domino_binary_folder is the folder containing Domino native libraries, for example, /opt/lotus/notes/latest/sunspa for Solaris, and /opt/lotus/notes/latest/linux for Linux.
Start IBM TDI with the Domino user (do not use root). The Domino user is called notes unless it is changed during the installation of the Domino Server.
Go to the root_directory/examples/dominoUsersConnector directory of the IBM TDI installation.
Registering Users in Domino using Java.
The Domino Administration Process is a program that automates many routine administrative tasks. For example, if you delete a user account, the Administration Process locates that user's name in the Domino Directory and removes it, locates and removes the user's name from ACLs, and makes any other necessary deletions for that user. When you put a request in the Domino Administration Requests database the process carries out all required actions.
The Domino AdminP Connector is a special version of the Lotus Notes Connector. For the Domino AdminP Connector, it has been enhanced to have the capability to sign fields while adding a document to the Domino database. In comparison with the Lotus Notes Connector, the Database parameter is not visible (it is always set to admin4.nsf, the Domino Administration Requests database), and it has a new parameter: Admin Request Type.
The Domino AdminP Connector supports the following Connector modes:
Domino Administration requests need to be signed before they are added to the admin4.nsf database in order to be further processed by the Administration process. When you sign a document a unique portion of the user ID is attached to the signed note to identify you as author. Otherwise the following error appears:
All of the required fields in the request have not been signed. Cause of error - An unauthorized person or a non-Domino program edited a posted request. This indicates a failed security attack.
Special coding in the Domino AdminP Connector ensures that all items of the Lotus Domino Document are being signed before the Document is saved.
Even the Lotus Domino administrator should have the rights to "Run Unrestricted methods & operations" in order to be able to sign documents. This can be accomplished using the Domino Administrator by adding that account, for example, administrator/IBM, in the Server -> Security -> Run Unrestricted methods & operations list.
The Domino AdminP Connector has a set of predefined Administration requests schemas. They are described in its configuration file, tdi.xml, in a similar manner as the input/output schemas defined in all other Connectors. However, there are two differences:
Currently, there are only two types of Admin requests bundled in the configuration of this Connector. They have the following definition:
Attribute | Description |
---|---|
Form | The form of the request. Should be "AdminRequest". |
ProxyAction | Corresponds to the id of the request made. For RenameUser the id is "118". |
ProxyAuthor | The author of the request who must have administrative privileges. (for example, CN=administrator/O=IBM ). |
ProxyNameList | The Domino user's name to be modified. |
ProxyNewWebFirstName | The new first name of the user. |
ProxyNewWebLastName | The new last name of the user. |
ProxyNewWebMI | The new middle name of the user. |
ProxyNewWebName | A new UserName to be added. |
ProxyProcess | The process of the request. Should be "AdminP". |
ProxyServer | The target server. Typically "*". |
ProxyWebNameChangeExpires | The expiration period of the request. The default is 21 days. |
Type | Type of the request. Should be "AdminRequest". |
Attribute | Description |
---|---|
Form | The form of the request. Should be "AdminRequest". |
ProxyAction | Corresponds to the id of the request made. For RenameGroup the id is "40". |
ProxyAuthor | The author of the request who must have administrative privileges. (for example, CN=administrator/O=IBM ). |
ProxyNameList | The Domino group's name to be modified. |
ProxyNewGroupName | The new name of the group. |
ProxyProcess | The process of the request. Should be "AdminP". |
ProxyServer | The target server. Typically "*". |
ProxyWebNameChangeExpires | The expiration period of the request. The default is 21 days. |
Type | Type of the request. Should be "AdminRequest". |
These Schemas are returned when you perform a Discover Attributes action in the Configuration Editor.
All
No attributes defined.
The "Rename User" and "Rename Group" schemas define the necessary fields to rename a user or group in a Domino Directory with samples of the values needed. The other schema ("All") is empty and used for any other type of requests; in order to use these add new schemas with valid attributes and corresponding new dropdown items.
The Connector needs the following parameters:
Attention: As RichTextItems are not serializable, enabling this option will cause an Exception if an attribute is mapped to another Domino database or is used remotely.
The Lotus Notes Connector provides access to Lotus Domino databases.
It enables you to do the following tasks:
Lotus Notes Connector requires Lotus Notes to be release 7.0 or higher.
For Lotus Notes Connector using Local Client or Local Server modes only: you might not be able to use the IBM TDI Config Editor to connect to our Notes database. Sometimes, the Notes Connector prompts the user for a password even though the Notes Connector provides it to the Notes APIs. The prompt is written to standard-output, and input from the user is read from standard-input. This prompting is performed by the Notes API and is outside the control of IBM TDI:
When the Session Type is LocalClient, we can start your Notes or Designer client and permit other applications to use its connection by setting a flag in the File -> Security -> User Security panel; click Security Basics, and select Don't prompt for a password from other Lotus Notes-based programs (reduces security) under "Your Login and Password Settings.". In this case, the Notes Connector (that is, the Notes API) ignores the provided password and reuses the current session established by the Notes or Designer client. The Notes or Designer client must be running to enable IBM TDI to reuse its session.
We can switch to using DIIOP mode to configure your AssemblyLines and switch back to Local Client or Local Server mode when we run the AssemblyLine through IBM TDI Server.
The following session types are supported (also refer to Supported session types by Connector for more information regarding libraries, setups and incompatibilities with other Domino Connectors):
With this session type, the Username parameter (dominoLogin) is ignored. The Password (dominoPassword) must match the password in the ID file used or the local Notes client prompts for a password. The Domino Server IP Address, IOR String, HTTP Port and Use SSL parameters are disregarded too for this session type.
This can be difficult, for example, when we run an AssemblyLine with standard input or output detached from the console. Always try to run an AssemblyLine in a command line window to detect whether the local client is prompting for the password. Testing shows that the local client ignores the correct Password parameter and always prompts for a password. One way of making sure the prompt is avoided is to do the following steps:
The Connector can use IIOP to communicate with a Domino server. To establish an IIOP session with a Domino server, the Connector needs the IOR string that locates the IIOP process on the server.
When you configure the Notes Connector, specify a hostname and, optionally, a port number where the server is located. This hostname:port string is in reality the address to the Domino server's http service from which the Connector retrieves the IOR string. The IOR string is then used to create the IIOP session with the server's IIOP service (diiop). The need for the http service is only for the discovery of the IOR string. This operation is very simple. The Connector requests a document called /diiop_ior.txt from the domino http server that is expected to contain the IOR string. We can replace the hostname:port specification with this string and bypass the first step and also the dependency of the http server. The diio_ior.txt file is typically located in the data/domino/html directory in your Domino server installation directory. Check the Web configuration in the Lotus Administrator for the exact location.
To verify the first step, go to the following URL: http://hostname:port/diiop_ior.txt where hostname is the hostname, and port is the port number of the domino server. You receive a document that says IOR: numbers. If you get a response similar to this, the first step is verified. If this fails, check both the HTTP configuration on the server that it enables anonymous access, and verify that the process is running.
When configuring an IIOP session, in order
to be able to browse available databases in the configuration of the
Connector in the Config Editor, the Domino server must support that
and also allow the various controls be populated with lists of available
databases, views, forms and agents. The Domino server setting to make
databases available for browsing is located under Server document -> Internet Protocols -> HTTP
tab -> Allow HTTP clients to browse databases. It must be set
to Yes and the Domino server must be restarted.
The Connector needs the following parameters:
Attention: As
RichTextItems are not serializable, enabling this option will cause
an Exception if an attribute is mapped to another Domino database
or is used remotely.
UNID is the universally unique ID of a Notes document -
it is unique even across database replicas.
The Notes API does not allow the UNID to be used directly in a
search filter passed to the Notes/Domino search functions. That is
why adding the option of using the UNID in search criteria will be
accomplished in the following way:
The described functionality will not cause backward compatibility
issues because the Notes API does not allow UNIDs in formulas/search
filters.
Lotus Domino documents contain items of type lotus.domino.RichTextItem.
Traditionally, when read, such items are received in the attribute
map of an Entry as plain text and vice-versa - written as plain
text back to the domino document. The Connector supports additional
functionality for these kind of items:
Creating a RichTextItem
Extracting attachment from a RichTextItem
For more information and examples see the Domino documentation
at: http://www-128.ibm.com/developerworks/lotus/documentation/dominodesigner/
The lotus.domino.RichTextItem class is not serializable
and items of this type can not be transferred through RMI. This will
cause a java.io.NotSerializableException when an Object of this type
is accessed through Remote Server APIs. Once a not serializable object
gets into the Entry the whole Entry becomes not serializable.
This also applies to the lotus.domino.DateTime class.
Also, this serialization limitation restricts lotus.domino.RichTextItems
to be transferred between different Domino databases. For this reason
a RichTextItem can be added/updated only with another RichTextItem
from the same database or with a RichTextItem
created with a script using the domino API, but still for the same
database.
The Connector can only directly manipulate Lotus Notes database
entries, but not database properties. However, database quotas can
be set by means of scripting, using a Script Component and a configured Lotus Notes Connector.
The sample code below should set file size quota and write the desired
MailOwnerAccess to the ACL.
To have IBM TDI access your Domino server, enable it through Domino Administrator
-> Security -> IIOP restriction. The user account you configured
for the IBM TDI to use must belong to a group listed under Run restricted Java/Javascript and Run
unrestricted Java/Javascript.
The Domino Web server must be configured to enable
anonymous access. If not, the current version of the Notes Connector
cannot connect to the Domino IIOP server.
If we want to encrypt the HTTPPassword field
of a Notes Address Book, add the following code to our
AssemblyLine:
Configuration
Select Form="Person"
UNID Support
Support of RichText attributes
Example scripts
var rti = NotesConnectorName.connector.getDominoSession().getDatabase("", <database_name>).createDocument().createRichTextItem("Body");
var header = NotesConnectorName.connector.getDominoSession().createRichTextStyle();
header.setBold(lotus.domino.RichTextStyle.YES);
header.setColor(lotus.domino.RichTextStyle.COLOR_YELLOW);
header.setEffects(lotus.domino.RichTextStyle.EFFECTS_SHADOW);
header.setFont(lotus.domino.RichTextStyle.FONT_ROMAN);
header.setFontSize(14);
rti.appendStyle(header);
rti.appendText("Sample text which will be formatted with the above style.");
work.setAttribute("Body", rti);
var doc = NotesConnectorName.connector.getDominoSession().getDatabase("", <database_name>).getAllDocuments().getFirstDocument();
if (doc.hasEmbedded()) {
var body = doc.getFirstItem("Body");
var rtnav = body.createNavigator();
if (rtnav.findFirstElement(
lotus.domino.RichTextItem.RTELEM_TYPE_FILEATTACHMENT)) {
do {
var att = rtnav.getElement();
var path = "c:\\Files\\" + att.getSource();
att.extractFile(path);
main.logmsg(path + " extracted");
} while (rtnav.findNextElement());
}
else
main.logmsg ("No attachments");
}
else
main.logmsg ("No attachments or embedded objects");
RichText limitations
Setting quota and file ownership
//NotesIterator is the NotesConnector name in the AssemblyLine
var db = NotesIterator.connector.getDominoDatabase(null);
//uses the public getDominoDatabase(...) method of the NotesConnector class;
//giving null for method parameter will return the database configured in the Connector
main.logmsg("Old quota: " + db.getSizeQuota());
//should print the old database size quota
db.setSizeQuota(5000);
//sets the size quota to 5000KB
main.logmsg("New quota: " + db.getSizeQuota());
//will print the new database size quota in kilobytes, i.e. 5000
var acl = db.getACL();
//get the database access control list
var ACLEntry = acl.createACLEntry("DesiredNotesUser", lotus.domino.ACL.LEVEL_MANAGER);
//create new ACL Entry
ACLEntry.setUserType(lotus.domino.ACLEntry.TYPE_PERSON); //set user type equal to Person
acl.save();
//save the access control list
Security
var pwd = "Mypassword";
var v = dom.connector.getDominoSession().evaluate
("@Password(\"" + pwd + "\")" ) ;
ret.value = v.elementAt(0);
This code uses Domino's password
encryption routines to encrypt the variable pwd.
It can be used anywhere that we want to encrypt a string using the @Password function that Domino provides.
A good place to use this code is in the Output Map for
the HTTPPassword attribute.
See also