Testing and Troubleshooting

5 Testing and Troubleshooting

After you deploy the connector, you must test it to ensure that it functions as expected.

This chapter discusses the following topics related to connector testing:

5.1 Testing the Connector

You can use the testing utility, supplied with the OIM Lotus Notes/Domino Connector package, to test basic provisioning operations (create, update, or delete) on a configurable target resource. The testing utility is implemented using ICF to invoke connector operations on the Domino Identity Connector, which is an approach that is quite similar to a Domino Connector deployed in OIM. You can configure the testing utility to use the connector server.

Note:

Before running the testing utility, you must place Notes.jar files in JAVA_HOME/jre/lib/ext or with classpath.

To use the testing utility, perform the following steps:

Set the CLASSPATH variable to contain the following jars:
- connector-framework.jar
- connector-framework-internal.jar
- groovy-all.jar
Note:

These are files are delivered as part of the OIM EAR application, and they are located in the oim.ear/APP-INF/lib directory.

You must add these three jar files to the JAVA_HOME/jre/lib/ext folder to run the test utility.
Unzip the OIM Domino Connector zip file.
Locate the test-utility directory.

Update the example-config.groovy file to reflect your local settings. The example-config.groovy file contains the following content:

>>>> example-config.groovy >>>>>>>>
import org.identityconnectors.common.security.GuardedString
 
// ICF  Configuration
icf {
    bundleName = 'org.identityconnectors.domino'
    bundleVersion = '2.0.1'
    connectorName = 'org.identityconnectors.domino.DominoConnector'
    //bundle = ''
    // Configure your connector server instance
    connectorServer {
        host = 'myhost'
        port = 8759
        key = 'mykey'
    }
}
 
// Connector Configuration - update with your environment information
connector {
    adminIdFile = 'c:\\Notes85\\Data\\user.id'
    adminName = 'administrator/ACME'
    adminPassword = new GuardedString)
    administrationServer = 'myreg.server.example.com'
    certifierIdFile = 'c:\\data\\cert.id'
    certifierPassword = new GuardedString)
    createIdFile = true
    createMailDB = false
    registrationServer = 'mycert.server.example.com'
    userDatabaseName = 'names.nsf'
    mailFileAction = 2
}
 
 
// put your own data here
first = 'tuFirst'
last = 'tuLast'
certorg = '/ACME'
 
// Create Account Attribute, no need to change it
create {
    FirstName = first
    LastName = last
    __NAME__="${first} ${last} ${certorg}".toString()
    ShortName = first[0].toLowerCase() + last
    __PASSWORD__ = new GuardedString("somepassword1".toCharArray())
    CertifierOrgHierarchy = certorg
}
 
// Update Account Attribute, no need to change it
update {
    FirstName = "updated"
}
 
// Flag if the created account should be deleted, comment the whole section if you don't want the user to be deleted
delete {
}
 
<<<<< end of example-config.groovy <<<<<<<

This file is divided into the following sections:

The "ICF section, which includes the following properties

Property Name	Description
bundleName, bundleVersion, connectorName	Denotes which Identity connector should be used by the test-utility. This information is preconfigured for the Domino Identity Connector, so no changes are required here.
connectorServer	Update this section based on your environment.
host	Connector Server host (hostname or IP address)
port	Connector Server port
key	Connector Server key

The Connector section contains configuration information that is specific to the Identity connector and it is similar to the IT Resource configuration in OIM. The configuration properties in this section are the same as those in the Lotus Notes IT Resource.

Table 5-1 IT Resource Parameters

Parameter	Description
`adminIdFile`	Fully-qualified path to the Administrator ID file. For example: `C:\Lotus\Notes\Data\admin.id`
`adminName`	Administrator account name, such as Administrator/ACM
`adminPassword`	Administrator password.
`administrationServer`	Name of the host where the administration server is running.
`certifierIdFile`	Fully-qualified path to the Certifier ID file. For example: `C:\Lotus\Domino\Data\cert.id`
`certifierPassword`	Password for the specified Certifier ID file.
`createIdFile`	Enter `True` if you want a mail file to be created with the ID file when the Register New User function of IBM Lotus Notes and Domino is called. Otherwise, enter `False`. Default is: `True`.
`createMailDB`	Indicates whether to set up mail when a user is created. If checked (`True`), mail setup occurs at account creation. If unchecked (`False`), mail setup occurs at first login. Default is: `True`.
`MailFileAction`	Use this parameter to specify how mail file deletion must be performed when a user is deleted. You can specify one of the following values: `Delete None` (`0`): Specifying this value leaves the users mail file. `Delete Home` (`1`): Specifying this value deletes the mail file on the users home server. `Delete All` (`2`): Specifying this value deletes the mail file on the users home server and all replicas. Default is: `2`.
`registrationServer`	Enter the canonical name of the server to be used when creating IDs and performing other registration functions. Sample value: `CN=MyServer/OU=MyOrg`
`userDatabaseName`	Specify the filename of the user database.

Run the following command:

java -classpath ./test-utility.jar oracle.iam.connectors.testutility.Main example-config.groovy

You should see output similar to this:

jThread Id: 1    Time: 2011-04-19 20:22:21.316   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: OK 
Message: Using remote connection info [{host=myhost.oracle.com, port=8759}]
Thread Id: 1    Time: 2011-04-19 20:22:32.065   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: OK
Message: Using ConnectorKey [ConnectorKey(
bundleName=org.identityconnectors.domino bundleVersion=2.0.1
connectorName=org.identityconnectors.domino.DominoConnector )]
Thread Id: 1    Time: 2011-04-19 20:22:32.065   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: OK
Message: Using ConnectorInfo
[org.identityconnectors.framework.impl.api.remote.RemoteConnectorInfoImpl@12d26d2]
Thread Id: 1    Time: 2011-04-19 20:22:32.067   Class:
oracle.iam.connectors.testutility.TestUtility
Method: doTest  Level: INFO     Message: Connector configured
Thread Id: 1    Time: 2011-04-19 20:22:32.081   Class:
oracle.iam.connectors.testutility.TestUtility    
Method: doTest  Level: INFO     Message: Got Connector Instance, ready to do the tests
Thread Id: 1    Time: 2011-04-19 20:22:32.086   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: INFO 
Message: Running 'test' operation on connector
Thread Id: 1    Time: 2011-04-19 20:22:32.086   Class:
org.identityconnectors.framework.api.operations.TestApiOp        Method: test
Level: OK Message: Enter: test()
Thread Id: 1    Time: 2011-04-19 20:22:39.333   Class:
org.identityconnectors.framework.api.operations.TestApiOp        Method: test
Level: OK Message: Return: null
Thread Id: 1    Time: 2011-04-19 20:22:39.333   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: INFO
Message: 'test' operation succeeded
Thread Id: 1    Time: 2011-04-19 20:22:39.333   Class:
oracle.iam.connectors.testutility.TestUtility    Method: doTest  Level: INFO
Message: Running 'create' operation on connector
... etc

5.2 Troubleshooting

The following table lists solutions to some commonly encountered issues associated with the IBM Lotus Notes and Domino connector.

Problem Description	Solution
nlsxbe.dll is not found.	Ensure that Notes install directory is included in PATH. Set LD_LIBRARY_PATH to Notes Install directory. Note: It is not recommended to have Domino Server & Lotus Notes on the same server. If you do so for testing purpose, ensure that the LD_LIBRARY_PATH points to Notes directory and not Domino directory. Also Domino install location should not be part of PATH variable. This may conflict proper working of connector.
Oracle Identity Manager cannot establish a connection with the IBM Lotus Notes and Domino server.	Ensure that the IBM Lotus Notes and Domino server is running. Ensure that Oracle Identity Manager is running. Ensure that all the adapters have been compiled. Use the IT Resources form to examine the Oracle Identity Manager record.
An Operation Failed message is displayed on the Oracle Identity Manager Administrative and User Console	Ensure that the attribute values do not contain delimiter characters (white space). Ensure that the attribute values do not exceed the specified length.
The prompt for the password was aborted by user	The certifier account password specified as the value of the `CertPwd IT` resource parameter is not correct. Specify the correct password, and then try again.
Destination path does not exist	The directory path specified as the value of the `IDFilePath IT` resource parameter is not correct. Specify the correct path, and then try again.
Restricted operations not allowed in the server	The administrator whose user ID you have provided in the `Admin IT` resource parameter must belong to the Full Access Administrator list. Ensure that the administrator belongs to this list, and then try again.
Could not open the ID file	The path of the certifier ID file that you have specified as the value of the `CertPath IT` resource parameter is not correct. Specify the correct path, and then try again.
File does not exist (<username>)	The name of the mail template file specified as the value of the `MailTemplateName` IT resource parameter is not correct. Ensure that the mail template file exists on the target Domino server. This file is typically found in the data directory of the Domino server. Specify the correct mail template file name and then try again. For example, the name of the mail template file for IBM Lotus Notes and Domino Server version 6.x is `mail6.ntf`.
Following error encountered when user is updated: `java.lang.IllegalArgumentException: Invalid Uid`	When you manually push the certorg data to the lookup definition, ensure that the case sensitivity of the certorg data is retained.
Following error is encountered when you modify the account after running the target user reconciliation: error occurred in oracle.iam.provisioning.handlers.ModifyAppInstanceAccountActionHandler while modifying account with key 563 associated to user with key 9004 and the cause of the error is An error occurred in oracle.iam.provisioning.spi.DOBProvisioningMechanism/modify while modifying account with account id 563 for user ERROR and the cause of error is Thor.API.Exceptions.tcAPIException: Error occurred while setting form data for process instance with key 1271.. oracle.iam.ui.platform.exception.OIMRuntimeException: IAM-40600019 : An error occurred in oracle.iam.provisioning.handlers.ModifyAppInstanceAccountActionHandler while modifying account with key 563 associated to user with key 9004 and the cause of the error is An error occurred in oracle.iam.provisioning.spi.DOBProvisioningMechanism/modify while modifying account with account id 563 for user ERROR and the cause of error is Thor.API.Exceptions.tcAPIException: Error occurred while setting form data for process instance with key 1271.. at oracle.iam.ui.platform.exception.OIMErrorHandler.reportServiceException(OIMErrorHandler.java:178) at oracle.iam.ui.platform.exception.OIMErrorHandler.reportException(OIMErrorHandler.java:66) at oracle.adf.model.binding.DCDataControl.reportException(DCDataControl.java:429) at oracle.adf.model.binding.DCBindingContainer.reportException(DCBindingContainer.java:448) at oracle.adf.model.binding.DCBindingContainer.reportException(DCBindingContainer.java:503) at oracle.adf.model.binding.DCControlBinding.reportException(DCControlBinding.java:208) at oracle.jbo.uicli.binding.JUCtrlActionBinding.reportException(JUCtrlActionBinding.java:2292) at oracle.jbo.uicli.binding.JUCtrlActionBinding.doIt(JUCtrlActionBinding.java:1848) at oracle.adf.model.binding.DCDataControl.invokeOperation(DCDataControl.java:2350) at oracle.jbo.uicli.binding.JUCtrlActionBinding.invoke(JUCtrlActionBinding.java:835) at oracle.adf.controller.v2.lifecycle.PageLifecycleImpl.executeEvent(PageLifecycleImpl.java:414) at oracle.adfinternal.view.faces.model.binding.FacesCtrlActionBinding._execute(FacesCtrlActionBinding.java:257) at oracle.adfinternal.view.faces.model.binding.FacesCtrlActionBinding.execute(FacesCtrlActionBinding.java:215) at oracle.iam.ui.platform.utils.FacesUtils.executeOperationBinding(FacesUtils.java:188) at oracle.iam.ui.platform.utils.FacesUtils.executeOperationBindingFromActionListener(FacesUtils.java:130) at oracle.iam.ui.catalog.view.backing.CartReqBean.submit(CartReqBean.java:1250) at oracle.iam.ui.catalog.view.backing.CartReqBean.submitActionListener(CartReqBean.java:1152) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:498) at com.sun.el.util.ReflectionUtil.invokeMethod(ReflectionUtil.java:181) at com.sun.el.parser.AstValue.invoke(AstValue.java:289) at com.sun.el.MethodExpressionImpl.invoke(MethodExpressionImpl.java:304) at org.apache.myfaces.trinidadinternal.taglib.util.MethodExpressionMethodBinding.invoke(MethodExpressionMethodBinding.java:62) at org.apache.myfaces.trinidad.component.UIXComponentBase.broadcastToMethodBinding(UIXComponentBase.java:2028) at org.apache.myfaces.trinidad.component.UIXCommand.broadcast(UIXCommand.java:183) at org.apache.myfaces.trinidad.component.UIXComponent.broadcastInContext(UIXComponent.java:373) at oracle.adf.view.rich.event.ProxyEvent.broadcastWrappedEvent(ProxyEvent.java:72) at oracle.adf.view.rich.component.fragment.UIXRegion._handleProxyEvent(UIXRegion.java:939)	As a workaaround, perform the following steps: On the Design Console, select the UD_LOTUS form from the form designer Create a new version of the form, click Properties, and remove the required property from Password field. Save the form and activate the new version.