___________________________________________________________________________________
IBM Tivoli Identity Manager
Dispatcher Component for Directory Integrator-based Adapters
IBM Tivoli Identity Manager Dispatcher Component for Directory Integrator-based Adapters is available. Compatibility, installation, and other getting-started issues are addressed.
Component Features and Purpose
Installation and Configuration Notes
These Release Notes contain information for the following products that was not available when the IBM Tivoli Identity Manager manuals were printed:
· IBM Tivoli Identity Manager Dispatcher Component Installation and Configuration Guide
The Dispatcher Component is designed to support integration between Tivoli Directory Integrator and Identity Manager. The Dispatcher is shipped with each Directory Integrator based adapter and is updated to the current release version with each adapter release. This package provides the Dispatcher as a separately shipped component to fast track upgrade and maintenance delivery.
|
Component |
Version |
|
Release Date |
2017 February 28 02.42.09 |
|
Package Version |
5.1.37 |
|
Component Versions |
Dispatcher build: 5.1.37.89 |
|
Documentation |
· Directory Integrator RMI Dispatcher Installation and Configuration Guide Version 5.1 (SC23-9626-00) |
|
Enhancement # (FITS) |
Description |
|
|
Items included in Current version (5.1.37) |
|
|
None |
|
|
Items included in 5.1.35 version |
|
|
None
|
|
|
Items included in 5.1.34 version |
|
|
None
|
|
|
Items included in 5.1.33 version
|
|
|
None
|
|
|
Items included in 5.1.32 version |
|
RFE23019 17132 (7374)
|
In this release, a new feature has been added to the RMI Dispatcher at service level. With this new feature, when a test operation completes successfully, the Assembly Lines for that service will be removed from the Assembly Line cache. In addition, any Assembly Lines that were running when the test operation was fired, will also not be cached when they complete. Thus, now the dispatcher won’t require a restart if any attribute on the service form has been changed and the test operation has been completed successfully. For details refer to the following section:
17132 (7374) and RFE23019:Purge RMI Dispatcher Cache
|
|
RTC 119318 |
A timed out request should be retried or failed is now configurable
For details refer to the following section:
RTC 119318:Internal: Optionally, fail time-out requests
|
|
|
Items included in 5.1.31 release |
|
RFE 30084 |
Default ALCacheSize For the unique requestID cannot be captured from TCB Dispatcher now preserves unique requestID. For details refer to following section: New attribute added to TCB to preserve unique requestID of a request (RFE30084)
|
|
|
Items included in 5.1.30 release |
|
|
None
|
|
|
Items included in 5.1.29 release |
|
|
The assembly lines can now be synchronized at the dispatcher level using a locking mechanism. For details refer to the following section:
Locking feature for AL Synchronization.
|
|
|
Items included in 5.1.28 release |
|
|
None
|
|
|
Items included in 5.1.27 release |
|
|
The time that the dispatcher sleeps after a timeout interrupt happens to allow cleanup, is now configurable. For details refer to the following section:
Configurable sleep time for Dispatcher
|
|
|
Items included in 5.1.24 release |
|
|
|
|
MR100110436 |
Dispatcher - Provide some sort of time out for TDI/RMI adapter requests. For details, refer the "Installation and Configuration Notes, Corrections to Install Guide" section. |
|
17069 (7313) |
ITIMAd script should include output file instead of /dev/null. For details, refer the section named "Output file for ITIMAd script" in the "Installation and Configuration Notes"
|
|
30530 (17466)
APAR IV27993 |
PMR 60438,300,624 Caching in RMI Dispatcher
|
|
|
Items included in 5.1.7 release |
|
|
|
|
N/A |
Updated Installation Program. Installer is now built using Install Anywhere (2009). Silent installation is now provided. See "Corrections to Installation Guide" for more information. |
|
N/A |
Non-root installation support. The dispatcher installer will no longer need root permissions to run. Installer can be run from any user's account as long as that particular user account have read, write and execute permissions on ITDI_HOME directory, its subfolders and ITDI Solution directory.
|
|
|
Items included in 5.1.6 release |
|
|
None
|
|
|
Items included in 5.1.5 release |
|
MR0804085838 |
Multiple RMI dispatchers installation is required on the same machine |
|
|
Items included in 5.1.4 release |
|
MR0507096955 |
SiebelJDB Adapter needs support for Siebel 8.1
This release of Dispatcher is updated to provide support for the above enhancement. Changes made in SiebelJDBAdapterUtils.java component of Dispatcher, for SiebelJDB adapter to support Siebel8.1
|
|
|
Items included in 5.1.3 release |
|
None
|
|
|
|
Items included in 5.1.2 release |
|
|
None
|
|
|
Items included in 5.1.1 release |
|
|
Initial release for Tivoli Identity Manager v5.1
|
|
Internal# |
APAR# |
PMR# / Description |
|
||
|
|
|
Items included in Current release (5.1.37) |
|
||
|
PMR: 83722,695,760
Bug 2209
RTC 153767
|
IV91236 |
Assembly line cache maintenance is stopped once a request was failed |
|
||
|
PMR: 82636,033,724
Bug 2213
RTC 153767
|
IV91236 |
Dispatcher not closing cached Assembly Lines, so keeping connections open |
|
||
|
PMR: 82462,033,724
Bug 2176
RTC 153767
|
IV91236 |
RMI Dispatcher throwing IndexOutOfBoundsException |
|
||
|
Internal Bug 1987
RTC 138914 |
|
ISIM: Documentation wrong for RMI Dispatcher for cluster environments RTC 138914 : ISIM: Documentation wrong for RMI Dispatcher for cluster environments |
|
||
|
|
|
Items closed in 5.1.35 version |
|
||
|
Internal Bug 2047 |
|
Internal report of logging issue in latest dispatcher
|
|
||
|
PMR: 51402,227,000 |
RTC 145426 |
JMX remote connect dispatcher question/issue- System property was set with host name containing only IP address to resolve the JMX remote connect issue.
|
|
||
|
|
|
Items closed in 5.1.34 version |
|
||
|
PMR: 00492,499,000 |
RTC 137454 |
SSL connections fail to initialize in Dispatcher
For details, refer the "Installation and Configuration Notes, Corrections to Install Guide" section.
|
|
||
|
|
|
Items closed in 5.1.33 version |
|
||
|
Internal Bug 1813 |
|
When "ITIMAd stop" is executed, respective logs should be appended in ITIMAd_stdout.log file
|
|
||
|
Internal Bug 1771 |
RTC 125650
|
Submit for doc update for 6.0/7.0 dispatcher docs for ITIMAd reference in /etc/init.2
RTC 125650 : Submit for doc update for 6.0/7.0 dispatcher docs for ITIMAd reference in /etc/init.2
|
|
||
|
|
IV74585 |
RMI Dispatcher still seems to double the value of AssemblylineCacheTimeout (6.0.32)
|
|
||
|
|
|
Items included in 5.1.32 version |
|
||
|
Internal Bug1575
|
|
Reconciliation fails using Peopletools adapter - Added a null check in the escapeDNValue() method in AdapterUtils.java, to check if the passed in String is null, and if so, an empty string is returned. |
|
||
|
|
|
Items closed in 5.1.31 Release |
|
||
|
|
IV61292 |
Dispatcher doesn't lower connection count when AL filesystem path is incorrect
|
|
||
|
|
IV61588 |
Slash in reconcile filter syntax fails parsing on Dispatcher
|
|
||
|
|
|
Items closed in 5.1.30 release |
|
||
|
|
IV59786
|
Service Level Parameter ignored when the HostNameURL is undefined.
|
|
||
|
|
|
PMR 91098,077,649 Added the missing StringUtility file
|
|
||
|
|
|
Items closed in 5.1.29 release |
|
||
|
Internal |
|
Added missing utility files for i5OS and PeopleTools adapter. |
|
||
|
|
|
Items closed in 5.1.28 release |
|
||
|
|
IV54172 |
PMR 25670,999,000 ITIM 5.1 RMI Dispatcher returning new attributes related to test connection to ISIM 6.0 server
|
|
||
|
|
|
Items closed in 5.1.27 release |
|
||
|
|
|
The default values for the timeout in itim_listener.properties file have been set to zero. By default, there would be no timeout. One may configure it as per need as described in the following section.
|
|
||
|
|
|
Changes to TDI Adapters Dev. Reference Guide - Added note for implicit attributes
|
|
||
|
|
IV47103 |
In case the firewall is enabled, refer the following link to configure the port on which dispatcher remote object listens for RMI requests.
How to configure RMI to traverse firewalls
|
|
||
|
|
IV43453 |
RMI Development Reference guide needs to detail that multi adapters require unique AL names
|
|
||
|
|
|
Items closed in 5.1.24 release |
|
||
|
|
|
|
|
||
|
|
IV41298 |
Dispatcher CaseInsensitive Filter
|
|
||
|
|
IV35801 |
Dispatcher- Set AssemblylineCacheTimeout value gives twice the actual timeout
|
|
||
|
|
|
Items closed in 5.1.7 version |
|
||
|
|
|
|
|
||
|
|
|
Items closed in 5.1.6 version |
|
||
|
|
N/A |
N/A AdaptersException missing serialVersionUID.
|
|
||
|
|
N/A |
N/A GlobalRunALCount getting incremented twice if ITDIAgentException is thrown from AL.
|
|
||
|
|
|
Items closed in 5.1.5 version |
|
||
|
|
|
N/A Changed the JVM order of TDI 70 installer. Installer now first searches for IBM JVM. This change is applicable for only TDI70 installers. |
|
||
|
|
|
Items closed in 5.1.4 version |
|
||
|
|
None |
|
|||
|
|
|
Items closed in 5.1.3 version |
|
||
|
N/A |
PMR 48655,999,000 Dispatcher memory leak suspect - Dispatcher is running out of memory if TDI is 7.0. However it is working fine if TDI is 6.1.1.
|
|
|||
|
|
N/A |
PMR 10530,500,000 Customer defined custom TDI/RMI adapters to have logging defined at the AL level. This is opening a new file descriptor to the log file each time the AL runs and these are not closing.
|
|
||
|
|
N/A |
N/A AL cache interfering with GlobalRunALCount - The AL cache (ALCacheSize and AssemblylineCacheTimeout) is interfering with the GlobalRunALCount parameter yielding unexpected and undesirable results.
|
|
||
|
|
|
Items closed in 5.1.2 version |
|
||
|
|
N/A |
N/A Corrected release notes. Added configuration information on case insensitive filtering.
|
|
||
|
|
|
Items closed in 5.1.1 version |
|
||
|
|
|
Initial release for TIM v5.1
|
|
||
|
Internal# |
APAR# |
PMR# / Description |
|
|
|
Dispatcher on Windows User must not specify the service name which consists of blank spaces on either side of service name. However user can specify the blank spaces between the words of service name such TIM Adapters, Test Service etc. But TIM Adapter (Blank at the end) or TIM Adapters (Blank at start) will not create the service on windows.
|
|
|
|
Dispatcher on Unix If user has Dispatcher 5.720 or lower installed on his machine and tries to upgrade the dispatcher installation to version 5.722 then upgrading the installation may fail. For successful installation of Dispatcher 5.722 version, the user must first uninstall lower version dispatcher and then install the dispatcher 5.722.
|
|
|
|
Dispatcher installation issue on Windows Server 2012 Platform Installation of dispatcher on Windows Server 2012 fails. In order to install it, one must run the DispatcherInstaller.exe file in Compatibility mode. The following steps must be followed:
1. Right click on the installer file. 2. Select properties and navigate to the Compatibility Tab. 3. Select the checkbox for "Run this program in compatibility mode for:" 4. Select the "Windows 7" option from the dropdown menu. 5. Apply the changes and run the installer.
|
|
|
|
Reconciliation Operation Issue The reconciliation operation happens in the form of batches. The batch size is dependent on the "SearchResultSetSize" attribute, specified in the "itim_listener.properties" file. Thus, the first batch would be reconciliation of "#" accounts, where "#" is nothing but the value specified in the "SearchResultSetSize", and subsequent batches too would be present for reconciliation of the remaining accounts, each batch of the size "#". Now, if an error or timeout occurs while the first batch of accounts is being executed, one would be able to witness that the request has failed along with the relevant error message. However, if error or timeout occurs while the subsequent batches are being processed, the request would fail, but no error message would be seen along, as in the previous case. This is a server side issue, ISIM recon limitation. |
See the IBM Tivoli Identity Manager Dispatcher Installation Guide for detailed instructions.
The following corrections to the Installation Guide apply to this release:
1. Before installing this version of dispatcher, you need to uninstall the earlier versions of dispatcher. This installer cannot be run on top of existing dispatcher installation (builds 5.739 or earlier).
2. Dispatcher installer will not ask for instance name and port number while upgrade.
3. The user who is running the installer must have the execute permissions on "ps" command on non-windows platforms.
1. Before installing this version of dispatcher, you need to uninstall the earlier versions of dispatcher. This installer cannot be run on top of existing dispatcher installation (builds 5.124 or earlier).
2. Dispatcher installer will not ask for instance name and port number while upgrade.
3. The user who is running the installer must have the execute permissions on "ps" command on non-windows platforms.
The Following step for dispatcher SSL configuration must be corrected to the install guide in chapter 5: Configuring SSL authentication for the adapter.
Under the sub section "Importing the Security Directory Integrator CA
certificate in the WebSphere Application Server truststore", there are
some steps given.
Replace 4th step - “4. Select NodeDefaultTrustStore” with “4. For a single server environment, select NodeDefaultTrustStore. Otherwise, select CellDefaultTrustStore for a clustered environment".
The following must be added to the install guide in the Chapter 6. Troubleshooting the RMI Dispatcher installation, after sub section Tivoli Directory Integrator Application Monitoring console
Troubleshooting the dispatcher while using SSL Configuration
|
Problem description |
Solution |
|
After some amount of usage, maybe an hour or so, SSL connections from ISIM to the Dispatcher stop working because the RMI Registry loses it's reference to the SSL Connection Factory |
If Connection reset errors are found, set following
property in solution.properties file.
|
Steps:
1. Go to TDI_HOME\timsol\solution.properties
2. Set systemqueue.on=false and save the
file
3.Restart the Dispatcher service.
Changes to section: Verifying the installation (Chapter 3: Dispatcher Installation)
First row, of Table 5 is changed.
After installation, verify that the ITDI_HOME\jars\3rdparty\IBM folder has the following jars -
rmi-dispatcher.jar
Add the following information to Chapter 3. "Dispatcher Installation", under section "Start, Stop, and restart of the Dispatcher Service" sub-section “Starting, stopping, and restarting the Dispatcher service on AIX, HP-UX, Linux, and Solaris operating systems” , topic name “About this task” of the Dispatcher install guide :
About this task
The ITIMAd script file starts and stops the service. The adapter installation copies the file to an ISIM solution directory.
Make changes to the 3rd row of the table as follows:
“Table 7. UNIX based and Linux directories”:
|
Operating System |
Directory |
|
Linux and Solaris |
ISIM solution directory |
In this release, a new feature has been added to the RMI Dispatcher at service level. With this new feature, when a test operation completes successfully, the Assembly Lines for that service will be removed from the Assembly Line cache. In addition, any Assembly Lines that were running when the test operation was fired will also not be cached when they complete. Thus, now the dispatcher won’t require a restart if any attribute on the service form has been changed and the test operation has been completed successfully.
Replace the entire “Transaction Timeout Feature for Dispatcher" section in "Configuring the RMI Dispatcher" of the install guide with the following
Transaction timeout:
You can configure a transaction timeout for the Dispatcher when transactions fail or take too long to complete. For example, transaction failure occurs when a managed resource is not correctly configured.
You can set the timeout interval for a specific transaction time, such as ADD, Delete, or Reconciliation. The timeout feature does not determine the cause of the delay. The timeout ends the transaction and frees its resources.
After timeout, the Dispatcher ibmdi.log file contains an error message such as:
Time Out ....Dispatcher Interrupts Initialization Thread due to AL TimeOut....
For example:
executeALRequest ():2226 Time Out: 60 request id: 7226427570134735752 Dispatcher Interrupts Initialization Thread due to AL TimeOut.
Service Name: OracleTestService Assembly Line Name is :OracleManageUserAL
The IBM Tivoli Identity Manager Server marks the service instance that is associated with the adapter. By default, the dispatcher sends a communication error to IBM Tivoli Identity Manager so that all requests for that service remain pending until IBM Tivoli Identity Manager determines that the service is up and running. To configure retry requests for a service that is marked down, see the IBM Tivoli Identity Manager Administration Guide.
You can also configure the dispatcher to send a failure for the requests that have timed out, so that IBM Tivoli Identity Manager does not retry the requests.
See the ‘Fail timed out transactions’ section to configure this feature.
Add a new section ‘Fail timed out transactions’ after the " Transaction Timeout Feature for Dispatcher " section in "Configuring the RMI Dispatcher" of the install guide.
You can configure the dispatcher to send a failure for the requests that have timed out, so that IBM Tivoli Identity Manager does not retry the requests. This feature can be set at the dispatcher level, service type level or service instance level.
Dispatcher level affects all adapters running under the Dispatcher.
Using the itim_listener.properties file in the TDI_HOME directory, set the following property:
FailTimeoutRequest
By setting this value as 1, the ITIM will fail the time-out requests when the timeout occurs. Default value is 0, which executes the default behavior, i.e. ITIM retries the time-out requests.
To implement a change, restart the Dispatcher.
Service type level affects all the services of the same type. This setting takes precedence over the Dispatcher level setting.
To configure a service type setting, you must change the service.def files of the adapter profile JAR file.
Procedure
1. Extract the content of the adapter profile JAR file.
2. In the service.def file, add the following XML text under each operation:
<dispatcherParameter name="FailTimeoutRequest">
<default>true</default >
</dispatcherParameter>
Specify FailTimeoutRequest value in Boolean. A true value implies, the feature is enabled and hence ITIM fails the request when timeout occurs.
False Value implies, the request goes in pending state and ITIM retries the request.
3. Re-create the adapter profile JAR file.
4. Import the profile with the Manage Service Types window that IBM Tivoli Identity Manager provides.
5. Restart the Dispatcher.
Service Instance level:
Service instance level affects one service instance only. This setting takes precedence over the Dispatcher level and service type level settings.
To configure a service instance setting, you must change the service.def, schema.dsml, and CustomLabels.properties files of the adapter profile JAR file.
Procedure
1. Extract the content of the adapter profile JAR file.
2. In the schema.dsml file, create an attribute myFailTimeoutRequest as shown below
<attribute-type single-value = true>
<name>myFailTimeoutRequest </name>
<description>Optionally Fail the timed out request</description>
<object-identifier>myFailTimeoutRequest -OID</object-identifier>
<syntax> 1.3.6.1.4.1.1466.115.121.1.7</syntax>
</attribute-type>
3. Update the adapter service object class in the schema.dsml file to include the new attribute as optional attribute.
4. Modify the CustomLabels.properties file to include meaningful label for the new attribute:
myFailTimeoutRequest = Fail the Timeout Request
5. Modify the service.def file to map the service attributes to the dispatcher parameters:
<dispatcherParameter name="FailTimeoutRequest " source= " myFailTimeoutRequest">
<default>true</default>
</dispatcherParameter>
6. Re-create the adapter profile JAR file with the updated files.
7. Import the profile with the Manage Service Types window that IBM Tivoli Identity Manager provides.
8. Use the IBM Tivoli Identity Manager Form designer to add the new attributes to the adapter service form.
9. Restart the Dispatcher.
var tcbfield = task.getClass().getDeclaredField("tcb");
tcbfield.setAccessible(true);
var tcb = tcbfield.get(task);
var transactionId=tcb.getProperty("CurrentTCBReqId");
The following must be added to the install guide in the chapter "Configuring the RMI Dispatcher".
Description:
In this release, a new feature has been added to the RMI Dispatcher: AL Synchronization. This is an optional feature.
The assembly lines can now be synchronized at the dispatcher level using a locking mechanism. For this purpose, the dispatcher now provides a lock to the AL’s. The AL has to acquire the lock, before it can execute the code that needs synchronization. The lock has to be released after the code is executed. In this manner, the AL’s can achieve synchronization amongst themselves, by acquiring and releasing this lock as per requirement.
3. Acquiring and releasing the lock in the AL:
You can add code similar to the following code snippet to any hook of your AL, as per your requirement. However, do not add this in the PROLOG section when AL caching is enabled. The PROLOG section is not executed again after the AL is in the cache.
a. Acquiring the Lock:
In our example, we added the following in the Before Add hook.
var myALCfg = task.getConfigClone(); //Get AL config object.
var myALSettings = myALCfg.getSettings(); //Get AL settings object from AL config.
var LockName = myALSettingsgetStringParameter("LockName");
task.logmsg("Lock name is"+LockName);
var lock = java.lang.System.getProperties().get(LockName);
var timeout = 240; //The maximum time that AL should wait to acquire the lock.
if ( lock.tryLock(timeout, java.util.concurrent.TimeUnit.SECONDS) )
{
/*
Critical Section
*/
}
else
{
task.logmsg("Failed to acquire lock");
}
b. Releasing the lock:
The critical section would be part from when the lock is acquired, to the point when it is released. The lock can be released using the following:
if (lock!=null)
{
lock.unlock(); //Releases the lock
}
You can add this in the same hook, or in any hook you wish to, as per your requirement. However, be sure to release the lock at appropriate places, even in error paths if required. Not doing so may lead to an IllegalMonitorStateException.
The following must be added to the install guide in the chapter "Configuring the RMI Dispatcher".
The following must be added to the install guide in the chapter "Configuring the RMI Dispatcher".
Description:
In this release a new feature has been added to the RMI Dispatcher: Transaction Timeout. This is an optional setting.
In few instances, customers experienced that some of the transactions are taking too long to complete or even just hang with no indication of the cause. In most instances, the hung transactions were a result of a misconfigured managed resource.
In a summary, the Dispatcher can be configured to time out a transaction if the transaction does not complete within a configurable time period. The configurable time period can be set per transaction type (i.e. ADD, Delete, or Reconciliation). This feature does not determine the cause why a transaction is taking too long nor does it fix it. This feature simply kills the running transaction to free up resources on TIM and TDI.
Workflow:
· When this feature is enabled, a transaction shall timeout regardless of the reason why it is taking longer to complete than the configurable time period.
· Once a transaction times out, the Dispatcher will return a communication error to the TIM server.
· The dispatcher log file (ibmdi.log) will display an error message: Time Out ….Dispatcher Interrupts Initialization Thread due to AL TimeOut….
· For example: executeALRequest ():2226 Time Out: 60 request id: 7226427570134735752 Dispatcher Interrupts Initialization Thread due to AL TimeOut. Service Name :OracleTestService Assembly Line Name is :OracleManageUserAL
· On the TIM server, the service instance associated with the adapter will be marked down.
· Once a service is marked down on the TIM server, all requests for that service will stay in pending request until TIM determines that the service is up and running.
· Refer to the TIM server administration guide for detailed description on how TIM is configured to retry requests for a service that is marked down.
There are three ways to enable transaction timeout on the Dispatcher:
· Dispatcher level setting: affects all adapters running under the dispatcher (all services in TIM using this Dispatcher).
· Service Type setting: affects all services of the same type. This setting supersedes the dispatcher level setting.
· Service Instance setting: affects one service instance only. This setting supersedes service type and dispatcher level settings.
Using the itim_listener.properties file (located under the TDI home directory), the following properties are used to set the transaction time out period:
ExecuteSearchALTimeOut
ExecuteAddALTimeOut
ExecuteModifyALTimeOut
ExecuteDeleteALTimeOut
All values specified would be in seconds. Values can be adjusted as needed by your deployment. A value of 0 implies that transaction time out period is unlimited and hence is not enabled. You must stop and restart the Dispatcher for these properties to take effect.
Note: The default values for the above attributes have been set to zero. Thus, by default the timeout feature would be ignored. One may alter and set these to an integral value (a positive value only) as per one’s requirement and take advantage of this feature.
Service Type Setting:
Service type setting will take precedent over the dispatcher level setting.
Four dispatcher parameters have been added and can be used for each operation respectively:
· AddRequestTimeOut
· ModifyRequestTimeOut
· DeleteRequestTimeOut
· SearchRequestTimeOut
Steps to configure service instance settings will involve making change to the service.def files of the adapter profile jar file.
· Un-jar (extract the content) of the adapter profile jar file.
· In the service.def file, add the following XML text under each operation:
<dispatcherParameter name="AddRequestTimeOut">
<default> 60 </default >
</dispatcherParameter>
<dispatcherParameter name="ModifyRequestTimeOut">
<default> 60 </default >
</dispatcherParameter>
<dispatcherParameter name="DeleteRequestTimeOut">
<default> 60 </default >
</dispatcherParameter>
<dispatcherParameter name="SearchRequestTimeOut">
<default> 600 </default >
</dispatcherParameter>
All values are in seconds. Values can be adjusted as needed by your deployment. A value of 0 implies that transaction time out period is unlimited and hence is not enabled.
· Re-jar (recreate the adapter profile jar file) with the updated file.
· Using the TIM Manage Service Types, import the profile.
Service Instance Setting:
If there is a need to set transaction time out period at the service instance level, then you must add attributes to the service object class of the adapter and map these attributes to the dispatcher parameters in the service.def file.
Service instance setting will take precedent over service type setting and dispatcher level setting.
Steps to configure service instance settings will involve making change to the schema.dsml, CustomLabels.properties, and service.def files of the adapter profile jar file.
· Un-jar (extract the content) of the adapter profile jar file.
· Create attributes in the schema.dsml file of the adapter profile and add them to the adapter service object class. Consider the following attributes:
myAddRequestTimeOut
myModifyRequestTimeOut
myDeleteRequestTimeOut
mySearchRequestTimeOut
For each attribute, add the following in the schema.dsml file in the attribute definition section. Note that each attribute must have a unique name and object-identifier.
<attribute-type single-value = true>
<name> myAddRequestTimeOut </name>
<description>Time out period of Add request</description>
<object-identifier>myAddRequestTimeOut-OID</object-identifier>
<syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax>
</attribute-type>
· Update the adapter service object class in the schema.dsml file to include the new attributes as optional attributes.
· Modify the CustomLabels.properties to include meaningful labels for the new attributes.
For example:
MyAddRequestTimeout=Add requests time out
myModifyRequestTimeout=Modify requests time out
myDeleteRequestTimeout=Delete requests time out
mySearchRequestTimeout=Reconciliation requests time out
· Modify the service.def file to map the service attributes to the dispatcher parameters as follow:
<dispatcherParameter name="AddRequestTimeOut" source= "myAddRequestTimeOut">
<default>60</default >
</dispatcherParameter>
<dispatcherParameter name="ModifyRequestTimeOut" source= "myModifyRequestTimeOut">
< default>60</default >
</dispatcherParameter>
<dispatcherParameter name="DeleteRequestTimeOut" source= "myDeleteRequestTimeOut">
< default>60</default >
</dispatcherParameter>
<dispatcherParameter name="SearchRequestTimeOut" source= "mySearchRequestTimeOut">
< default>600</default >
</dispatcherParameter>
· Re-jar (recreate the adapter profile jar file) with the updated files.
· Using the TIM Manage Service Types, import the profile.
· Using the TIM Form Designer, add the new attributes to the adapter service form.
Note: You can use one attribute for all time out values on the service object class; just map the same attribute to each dispatcher parameter. Ideally, you can use two attributes: one for reconciliation and the other for all the other operations.
The following must be added to the install guide in the chapter "Troubleshooting the adapter errors".
In this release, we have added a new feature, specific to the installation of dispatcher on Unix/Linux machines. The ITIMAd script that is used to start/restart/stop the dispatcher service would now log its output to a separate file called "ITIMAd_stdout.log", which would be generated at "/opt/IBM/TDI/TDI_Version/timsol" folder (your solution directory folder). This output file would include the details of the dispatcher start/restart/stop operation. In case there is a problem in starting the dispatcher, the output of that operation generated in this file can be referred to identify the area where the operation failed.
The installer name for Dispatcher for TDI 70 has changed. It is now as follows –
DispatcherInstall_70.jar
DispatcherInstall_win_70.exe
DispatcherInstall_linux_70.bin
The itim_listner.properties file is a dispatcher configuration file and is present in the TDI Home directory. Upgrading dispatcher component will replace this property file with newer version but the installer will take care to create back up of old file. Similarly, the uninstaller will also create a backup of the itim_listner.properties file while uninstalling the dispatcher.
The back-up of this file will be created in the following format.
itim_listener.properties.1.backup
itim_listener.properties.2.backup
itim_listener.properties.3.backup
Updates to Install Guide:
1. To run the dispatcher installer in console mode, command switch has been changed from -console to -i console.
To run the installer in console mode, use following commands:
a) Installing the dispatcher on Windows:
DispatcherInstall_win_70.exe -i console
b) Installing the dispatcher on AIX, Solaris and HP-UX:
ITDI_HOME/jvm/jre/bin/java -jar DispatcherInstall_70.jar -i console
c) Installing the dispatcher on Linux:
./DispatcherInstall_linux_70.bin -i console
2. To run the installer in silent mode command switch has been changed from -silent to -i silent
To run the installer in silent mode, use following commands:
a) Installing the dispatcher on Windows:
DispatcherInstall_win_70.exe -i silent -DLICENSE_ACCEPTED=TRUE -DUSER_INSTALL_DIR="C:\Program Files\IBM\TDI\V7.0" -
DUSER_SELECTED_SOLDIR="C:\Program Files\IBM\TDI\V7.0\timsol" -DUSER_DISPATCHER_SERVICE_NAME="TIM Adapters" -DUSER_INPUT_PORTNUMBER=1099
b) Installing the dispatcher on AIX, Solaris and HP-UX:
DispatcherInstall_70.jar -i silent -DLICENSE_ACCEPTED=TRUE - DUSER_INSTALL_DIR="/opt/IBM/TDI/V7.0" -
DUSER_SELECTED_SOLDIR="/opt/IBM/TDI/V7.0/timsol" -DUSER_DISPATCHER_SERVICE_NAME="TIM Adapters" - DUSER_INPUT_PORTNUMBER=1099
c) Installing the dispatcher on Linux:
DispatcherInstall_linux_70.bin -i silent -DLICENSE_ACCEPTED=TRUE - DUSER_INSTALL_DIR="/opt/IBM/TDI/V7.0" -DUSER_SELECTED_SOLDIR="/opt/IBM/TDI/V7.0/timsol" -DUSER_DISPATCHER_SERVICE_NAME="TIM Adapters" - DUSER_INPUT_PORTNUMBER=1099
3. To run the dispatcher uninstaller in console mode, command switch has been changed from -console to -i console.
To run the uninstaller in console mode, use following commands:
a) Uninstalling the dispatcher on Windows:
DispatcherUninstall.exe -i console
b) Uninstalling the dispatcher on AIX, Solaris and HP-UX:
ITDI_HOME/jvm/jre/bin/java -jar uninstaller.jar -i console
c) Uninstalling the dispatcher on Linux:
ITDI_HOME/DispatcherUninstaller/DispatcherUninstaller -i console
4. To run the uninstaller in silent mode command switch has been changed from -silent to -i silent.
To run the installer in silent mode, use following commands:
1. Uninstalling the dispatcher on Windows:
DispatcherUninstall.exe -i silent
2. Uninstalling the dispatcher on AIX, Solaris and HP-UX:
ITDI_HOME/jvm/jre/bin/java -jar uninstaller.jar -i silent
3. Uninstalling the dispatcher on Linux:
ITDI_HOME/DispatcherUninstaller/DispatcherUninstaller -i silent
Important Notes:
1. The -D option is followed by a variable and a value pair without any space after the -D option.
2. You must wrap value with quotation marks when it contains spaces.
3. If you install dispatcher in silent mode, the uninstaller runs in silent mode irrespective of whether you are using -i silent option or not.
4. If you install the dispatcher in GUI mode, you can uninstall it in GUI, Console or silent mode.
5. If you install in console mode, you cannot uninstall in GUI mode. However you can use console and silent mode.
6. If you install dispatcher using DispatcherInstall_70.jar, use uninstaller.jar created in ITDI_HOME/DispatcherUninstaller directory to uninstall the dispatcher.
7. If you install dispatcher using DispatcherInstall_linux_70.bin, use DispatcherUninstaller file created in ITDI_HOME/DispatcherUninstaller directory to uninstall the dispatcher.
Starting, Stopping, and Restarting the RMI Dispatcher service:
1. If dispatcher service/process is already running before the upgrading the dispatcher, then the dispatcher installer will stop the service and restarts it after the completion of the dispatcher upgrade process.
2. If dispatcher service/process is not running before the upgrading the dispatcher, then the dispatcher installer will not start the service after the completion of the dispatcher installation process. However, if you want to start the dispatcher service forcefully, you must use following command line option when you run the dispatcher installer:
FORCE_DISPATCHER_SERVICE_START_ONINSTALL=yes.
For example: DispatcherInstall_win_70.exe - DFORCE_DISPATCHER_SERVICE_START_ONINSTALL=yes
Valid values for FORCE_DISPATCHER_SERVICE_START_ONINSTALL option are yes or no.
The following corrections configuration notes apply to this release:
By default this property in TDI 70 is true, so dispatcher always starts on the default remote port 1099. The default local port property value (16231) is overridden because TDI 7.0 sets the api.remote.on property value to true. To start the dispatcher on local port 16231, the default remote port value must be set or the api.remote.on property must be set to false.
Please note that if the dispatcher is installed without specifying the port or as port zero, the dispatcher will not listen at port zero but at any random port selected by OS.
On the adapter service form, the following are the attributes (or parameters) that will allow you to scale and tune the Dispatcher instance running within the Tivoli Directory Integrator:
1. "Disable AL Caching" service parameter:
By default, the Dispatcher will cache assembly lines for the add, modify, delete, and test operations. Caching an assembly line will retain connection to the managed resource and could improve performance. However, caching could introduce issues such as memory allocations and time-outs by the managed resource.
To disable assembly line caching for a particular service, select (check) the Disable AL Caching option on the service form under the Dispatcher Attributes panel.
Additional Caching Option (ALCacheSize):
There is a global cache setting at the Dispatcher level. You can specify the maximum number of assembly lines that the dispatcher caches for all services. To do so, set property ALCacheSize in the itim_listener.properties file. Refer to the adapter or dispatcher installation guide for more information on how to update the itim_listener.properties file. The default assembly line cache size is 100. Setting the assembly line cache size to 0 disables the caching in the dispatcher
2. "Max Connection Count" service parameter:
By default, the Dispatcher will run (execute) as many requests as it gets per service simultaneously. Such behavior could be beneficial if the managed resource can handle a high number of simultaneous connections. However, most managed resources support a limited number of simultaneous connections due to resource allocation or security precautions.
To specify the maximum number of assembly lines that the dispatcher can execute simultaneously for the service, enter a positive integer value for Max Connection Count on the service form under the Dispatcher Attributes panel. A value of 0 implies no limit.
In order for Max Connection Count to take effect, the following must be done:
(i) The GlobalRunALCount, in itim_listener.properties file, must be set to nonzero (Refer below).
(ii) After changing the value of Max Connection Count, you must restart the Dispatcher service.
Additional Connection Option (GlobalRunALCount):
The dispatcher allows an upper limit to be defined for the maximum number of assembly lines that can be executed simultaneously for all services. To do so, set property GlobalRunALCount in the itim_listener.properties file. Refer to the adapter or dispatcher installation guide for more information on how to update the itim_listener.properties file. The default value is 100
3. "AL File System Path" service parameter:
Optionally, you can now store the assembly lines on the file system where the dispatcher is running. This field is the full path to where the assembly lines files are located. The assembly file names should be the same as specified in the resource.def file.
This feature can be used to load customized assembly lines without the need to rebuild and import the profile. It will reduce the testing time as you can simply place the assembly line in a folder and submit a request from TIM.
For example, you can specify the following file path to load the assembly lines from the profiles directory of the Windows operating system: "C:\Program Files\IBM\TDI\V7.0\profiles" or you can specify the following file path to load the assembly lines from the profiles directory of the UNIX/Linux operating system: " /opt/IBM/TDI/V7.0/profiles".
Browse to ADAPTER_SOL_DIR and then fire below mentioned commands:
1. AIX:
a. ITIMAd startsrc: For starting the Dispatcher service.
b. ITIMAd stopsrc: For stopping the Dispatcher service.
c. ITIMAd restartsrc: For restarting the Dispatcher service.
2. LINUX/Solaris/HP-UX:
a. ITIMAd start: For starting the Dispatcher service.
b. ITIMAd stop: For stopping the Dispatcher service.
c. ITIMAd restart: For restarting the Dispatcher service.
Scenarios in which user can face problem:
A. Mixed Dispatcher Versions:
If two versions of the Dispatcher are used on a single server, both version of the Dispatcher must support the multiple Dispatchers feature. If previously released ITDI based adapters that doesn’t support multiple instances of Dispatcher is installed on Dispatcher that supports multiple instances:
a. Impact:
i. On Windows:
Adapter will get installed, but if multiple services are running or a non-TIM-Adapter TDI service is running then installer log will show error because it will not find the correct service to stop.
ii. On Solaris/Linux:
For Solaris and Linux platform ,service \ Subsystem name is not the issue as unique pid is created for each process, hence we can get the pid of dispatcher process running on mentioned TDI by user.
For Solaris/Linux platform, as in old adapter we start /stop the dispatcher service from etc\init.d\ folder, but from the release of Dispatcher 5.722, installer doesn’t copy ITIMAd script to etc\init.d folder; hence adapter installation may not be successful.
b. Work Around:
i. On Windows:
1. Stop the Dispatcher service, install the intended adapter and then restart the Dispatcher service.
ii. On Solaris/Linux:
1. Before installing the adapter on dispatcher that supports multiple instances manually stop the Dispatcher service from ADAPTER_SOL_DIR. Install the adapter. After successful installation of adapter, manually start the Dispatcher service.
2. Port Number specified by user should not be used by any other process OR all dispatcher services installed on a machine should be running (not stopped).
Consider a scenario, User installs Dispatcher on TDI70 in drive (say DRIVE1) which is listening at port 16231 and its service is started. Now user installs dispatcher on TDI611 in another drive (DRIVE2), if he enters the port no as 16231, then according to logic in custom bean for port validation, Installer will bounce back with Port already in use message. This is the case when another dispatcher service is listening on port 16231.
Now assume that service of dispatcher installed on DRIVE1 is stopped and then user installs the dispatcher on DRIVE2, then according to currently logic in custom bean for port validation, it will not find the port in use so the installer will proceed installing the dispatcher with port no value as 16231.Now when user try to start the first service which was stopped earlier, then it will give error in starting dispatcher service Port Already in use as second service has used 16231 port.
The IBM Tivoli Identity Manager Dispatcher was built and tested on the following product versions.
This component installs into Tivoli Directory Integrator (TDI) and may be installed on any platform supported by the TDI product and supported by the target system libraries or client, where applicable. IBM recommends installing TDI on each node of the ITIM WAS Cluster and then installing this adapter on each instance of TDI. Supported TDI versions include:
Adapter Installation Platform:
IBM Tivoli Directory
Integrator 7.1 with Fix Pack 5 or higher
IBM Tivoli Directory Integrator 7.1.1 with FP2 or higher
Managed Resource:
N/A
IBM Tivoli Identity Manager:
IBM Tivoli Identity Manager v5.1
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged should contact:
IBM Corporation
2ZA4/101
11400 Burnet Road
Austin, TX 78758 U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:
your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. Copyright IBM Corp. _enter the year or years_. All rights reserved.
If you are viewing this information in softcopy form, the photographs and color illustrations might not be displayed.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark informatio at www.ibm.com/legal/copytrade.shtml.
Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom.
Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries.
End of Release Notes