Directory Integrator, Version 7.1.1
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, you 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 you need to install Lotus Domino Server on the machine where Tivoli® Directory Integrator 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 Tivoli Directory Integrator 7.1.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 NotesExceptionProviding 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 NotesExceptionIf 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 NotesExceptionIn 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 > Connectors V |
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 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 Tivoli Directory Integrator, 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 you must have either a Notes Client or a Domino Server installed on the same machine as IBM Tivoli Directory Integrator). Most modern operating systems allow a process to use either 32-bit or 64-bit native binaries but not both. If you 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 you want to use Local Server (Local Client) session to a 32-bit Domino Server (Notes Client) (even on a 64-bit operating system), you need to use IBM Tivoli Directory Integrator with a 32-bit JVM.
There are a few configuration steps which must be performed after Tivoli Directory Integrator 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 you 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'-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'When an AssemblyLine (containing Connectors) is executed by the Tivoli Directory Integrator 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 Tivoli Directory Integrator Lotus Notes/Domino components require the presence of the ncso.jar file.
From IBM Tivoli Directory Integrator 6.1, ncso.jar will no longer be shipped with the Tivoli Directory Integrator product. You need to manually provide this file in order for the Tivoli Directory Integrator 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 Tivoli Directory Integrator_root\jars\3rdparty\IBM folder, so that the Tivoli Directory Integrator Server will load it on initialization. Since the ncso.jar will not be provided as part of the IBM Tivoli Directory Integrator 7.1.1 installation, some existing Tivoli Directory Integrator 6.0 functionality will change as follows.
The Tivoli Directory Integrator Server provides the "-v" command-line option which displays the versions of all Tivoli Directory Integrator components. Since the ncso.jar file will not be provided as part of the Tivoli Directory Integrator 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 undefinedThe Server API provides a method to request version information about Tivoli Directory Integrator 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.NotesExceptionAssemblyLines 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 Tivoli Directory Integrator 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 Tivoli Directory Integrator 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 Tivoli Directory Integrator 7.1.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.
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 Tivoli Directory Integrator V7.1.1 Password Synchronization Plug-ins Guide.
The Connector stores locally, on the IBM Tivoli Directory Integrator 7.1.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.
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, you 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, you must 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, you must 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 Tivoli Directory Integrator Server there is a different Connector-specific table in the System Store.
While the Connector is offline you 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 you 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 you 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 you need filtering you must 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.
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 you can increase the memory available to IBM Tivoli Directory Integrator.
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:
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 you 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 you 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".
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 you must 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 Tivoli Directory Integrator Java Virtual Machine (the JVM maximum heap size) is insufficient. In general the Java Virtual Machine does not use all the available memory. You can increase the memory available to the IBM Tivoli Directory Integrator JVM by following this procedure:
Edit ibmdisrv.bat file in the IBM Tivoli Directory Integrator install directory to change the heap memory size parameters (-Xms and -Xmx). Refer to the IBM Tivoli Directory Integrator V7.1.1 Problem Determination Guide for more details.
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.
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 you 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 Tivoli Directory Integrator.
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'.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.
The Domino Users Connector provides access to Lotus Domino user accounts and the means for managing them. With it, you 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; false - if the user belongs to at least one group of type "Deny List only". |
In Lookup mode, the Connector will perform different type of searches, depending on the value of the Use full-text search parameter:
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 Tivoli Directory Integrator V7.1.1 Password Synchronization Plug-ins Guide.
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 compatibility with pre-6.1 TDI configuration files.
"& Form = "Person"" Tivoli Directory Integrator 7.1.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 Tivoli Directory Integrator access the Domino Server, you might have to enable it through Domino Administrator -> Configuration -> Current Server Document -> Security -> Java/COM Restrictions. The user account you have configured the IBM Tivoli Directory Integrator to use must belong to a group listed under Run restricted Java/Javascript/COM and Run unrestricted Java/Javascript/COM.
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 you 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, you 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, you must 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:
| Attribute name | Type | Required for registration? | Value |
|---|---|---|---|
| REG_Perform | Boolean | Yes | If set to true the Connector performs user registration.
If this attribute is missing, or its value is false, the Connector does not perform user registration, regardless of the presence and the values of the other REG_ Attributes. |
| REG_IdFile | String | Yes | Contains the full path of the ID file to be
registered. For example,
|
| REG_UserPw | String | No | The user's password. |
| REG_Server | String | No | The name of the server containing the user's
mail file.
If the Attribute is missing, the value will be obtained from the current Connector's Domino Session. When the Connector is running on a Notes client machine and is registering a user, this Attribute must be specified in order to create a mail file on the server for the newly registered user. |
| REG_CertifierIDFile | String | Yes | The full file path to the certifier ID file. |
| REG_CertPassword | String | Yes | The password for the certifier ID file.
Note:
If the certifier password is wrong when registering users,
a popup window is displayed. Ensure that the Certifier password is
correctly specified. |
| REG_Forward | String | No | The forwarding domain for the user's mail file. |
| REG_AltOrgUnit | Vector of <String> | No | Alternate names for the organizational unit to use when creating ID file. |
|
REG_AltOrgUnit Lang |
Vector of <String> | No | Alternate language names for the organizational unit to use when creating ID file. |
| REG_CreateMailDb | Boolean/String | No | true - Creates a mail database;
false - Does not create a mail database; it is created during setup. If this attribute is missing, a default value of false is assumed. If this attribute is true, the MailFile attribute must be mapped to a valid path. |
| REG_MailTemplateFile | String | No | The filename of a Notes template database, which the Connector will use to create the user mail file. If this Attribute does not exist the default mail template is used. |
| REG_MailTemplateServer | String | No | The IP address or hostname of the Domino server machine on which the mail template database (specified by "REG_MailTemplateFile") resides. If this Attribute does not exist the local Domino server machine is used. |
| REG_MailDbInherit | Boolean/String | No | true - the user mail database to be created
will inherit any changes to the mail template database design;
false - the user mail database to be created will not inherit any changes to the mail template database design. If this Attribute is missing, a default value of "false" will be assumed. |
|
REG_StoreIDInAddress Book |
Boolean/String | No |
true - stores the ID file in the server's Domino Directory; false - does not store the ID file in the server's Domino Directory. If this Attribute is missing, a default value of "false" is used. |
| REG_Expiration | Date | No | The expiration date to use when creating the ID file. If the attribute is missing, or its value is null, a default value of the current date + 2 years is used. |
| REG_IDType | Integer/String | No | The type of ID file to create: 0 - create a
flat ID; 1 - create a hierarchical ID; 2 - create an ID that depends
on whether the certifier ID is flat or hierarchical.
If the attribute is missing, a default value of 2 is used. |
|
REG_Is NorthAmerican |
Boolean/String | No | true - the ID file is North American;
false - the ID file is not North American. If this attribute is missing, a default value of true is used. |
|
REG_MinPassword Length |
Integer/String | No | The REG_MinPasswordLength value defines the
minimum password length required for subsequent changes to the password
by the user. The password used when the user registers is not restricted
by the REG_MinPasswordLength value.
If this attribute is missing, a default value of 0 is used. |
| REG_OrgUnit | String | No | The organizational unit to use when creating the ID file. If this attribute is missing, a default value of " " is used. |
| REG_RegistrationLog | String | No | The log file to use when creating the ID file. If this attribute is missing, a default value of " " is used. |
|
REG_Registration Server |
String | No | The server to use when creating the ID file. This attribute is used only when the created ID is stored in the server Domino Directory, or when a mail database is created for the new user. |
|
REG_StoreID InAddressBook |
Boolean/String | No | true - stores the ID file in the server's Domino Directory false - does not store the ID file in the server's Domino Directory. If this attribute is missing, a default value of false is used. |
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:
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 you want, then no special configuration for the deletion is needed. You must specify the correct link criteria in the Delete Connector.
You 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.
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, you must 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_PATHwhere 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 Tivoli Directory Integrator 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 TDI_install_dir/examples/DominoUserConnector directory of your IBM Tivoli Directory Integrator 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 your 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.
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.
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 you must add new schemas with valid attributes and corresponding new dropdown items.
The Connector needs the following parameters:
The Lotus Notes Connector provides access to Lotus Domino databases.
It enables you to do the following tasks:
For Lotus Notes Connector using Local Client or Local Server modes only: you might not be able to use the IBM Tivoli Directory Integrator Config Editor to connect to your 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 Tivoli Directory Integrator:
When the Session Type is LocalClient, you 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 Tivoli Directory Integrator to reuse its session.
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.
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. You 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 your 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, you must check both the HTTP configuration on the server that it enables anonymous access, and verify that the process is running.
The Connector needs the following parameters:
Select Form="Person" 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 compatibility with earlier versions 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:
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");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.
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.
//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 listTo have IBM Tivoli Directory Integrator access your Domino server, you must enable it through Domino Administrator -> Security -> IIOP restriction. The user account you configured for the IBM Tivoli Directory Integrator 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.
var pwd = "Mypassword";
var v = dom.connector.getDominoSession().evaluate
("@Password(\"" + pwd + "\")" ) ;
ret.value = v.elementAt(0);