Example: Using IDI as a TIM End-Point to Manage Accounts

• defining a data model and adding it to the TIM data store
• configuring TIM for management of of the newly defined account type
• configuring an LDAP server to store the example accounts
  
• configuring IDI event handler and assembly line to accept account management requests
• running tests to provision, modify, and delete accounts
  

• schema.dsml defines the directory syntax for the account and service classes.
• resource.def is the resource definition for the creation of a service profile
• CustomLabels.properties defines labels for the forms displayed in the user interface

1. Copy the directory dsml2testservice and its contents from the examples folder to the location ${TIM_HOME}\data\remote_resources.
2. Bring up a command line interface and change directories to the {$ITIM_HOME}\bin\win.
3. Execute the command config_remote_services -profile dsml2testservice.
4. Restart the TIM server.

1. Customize the account and service forms.   Without customization the service form displayed will include some attributes that should be hidden and the attributes that should be displayed are not listed in a logical order.  This can was corrected with the form designer, however.  The form designer for account and service entities is shown in Figures 1 and 2.
   
   
   
   
   Figure 1 Form Design of Account Entity
   
   
   
   
   
   Figure 2 Form Design of Service Entity
   
   
   Notice the listbox widget used for the testgroupmembership attribute. This uses a search to allow users to search for group data brought back during reconciliation. To configure the search, double click on the widget in the designer and enter these values for in the dialog:
   
   

   Parameter	Value	Explanation
   Search Base	Contextual	Relative to the Service
   Attribute	dsml2groupname	Name of the attribute to display
   Filter	(objectclass=erdsml2testgroup)	How to narrow the values to select from.
   Multiple Value	checked	The use may add more than one value

   
   
2. Navigate to Provisioning | Service Management.
3. Add a new service of type dsml2testservice.
4. Add the following values for the test service parameters
   

   Parameter	Value	Explanation
   Service Name	dsml2 test	A value to display on the TIM user interface.
   URL	http://localhost:8800	This is needed to locate IDI.
   User ID	agent	The principal used for TIM to authenticate to IDI.
   Password	agent	The password used for TIM to authenticate to IDI.
   Naming Context	dc=ldap	Used to relate requests to the correct context within IDI.
   Category	Account	Type of entity for use with TIM data services API's.  This is the appropriate value for account management.

   
   
5. Create a provisioning policy for the new service.
   

Figure 3 Screen Shot of Custom Service Instance Detail Form

1. Add a naming context called dc=ibm
2. Under that naming context add an organizational unit called ou=white pages.  A screenshot of the LDAP server directory tree is shown in Figure 4, which shows the location of the ou=whitepages,dc=ibm branch.
3. Add an example inetOrgPerson under the newly created organizational unit.  Filling in the following attribute values:
   • dn: uid=dtrump,ou=white pages,dc=ibm
   • cn: donald trump
   • sn: trump
   • givenname: donald
   • mail: dtrump@trumptower.com
   • telephoneNumber: 123/456-789
   • uid: dtrump
     

1. Add an assembly line.  The name of the assembly line should be processAdd.  In the Call/Return tab of the assembly line add the names of the attributes defined in the schema.dsml file as Work Entry attributes.  Unselect the required checkbox on all of the attributes.  A screenshot with this configured is shown in Figure 5.
   
   
   
   
   Figure 5 Configuration of External Attributes in Assembly Line Call/Return Screen
   
   
   
2. Add a Connector to the assembly line.  The connector should be of type ibmdi.JNDI, called PersonAdd, and be in add only mode.  A screen shot is shown in Figure 6.  In the configuration tab, enter these values
   
   

   Parameter	Value
   JNDI Driver	com.sun.jndi.ldap.LdapCtxFactory
   Provider URL	<url of directory server>
   Referrals	Follow
   Authentication Method	Simple
   Login Name	<your login name>
   Login Password	<your password>
   Name Parameter	$dn
   Search Base	ou=white pages, dc=ibm
   Search Scope	Subtree

   
   
   
   
   
   Figure 6 Screenshot of JNDI Connector
   
   
   
3. In the Output tab of the connector click the Connect toolbar icon and then click the next toolbar icon.  This will allow IDI to determine the schema of the output source.  A list of available attributes will be listed as shown in Figure 7.
   
   
   
   
   
   Figure 7 Screenshot of Schema Introspection by JNDI Connector
   
   
   
4. In the Output Map tab of the connector add the values below.  The dn needs to remove the leading "er" from the attribute name "eruid" and append the base distinguished name.  A screen shot of the panel is shown in Figure 8.
   
   

   Connector Attribute	Mapping
   $dn	var incomingDN = work.getString("$dn"); var end = incomingDN.indexOf(","); var outgoingDN = incomingDN.substring(2, end) + "," + PersonAdd.getConnectorParam("ldapSearchBase"); ret.value = outgoingDN;
   cn	cn
   givenname	firstname
   mail	mail
   objectclass	ret.value="inetorgperson";
   sn	lastname
   telephoneNumber	telephoneNumber
   uid	eruid
   userpassword	erpassword

   
   
5. Add an event hander of type ibmdi.DSMLv2EventHandler named TIM Listener.  In the configuration screen set the port to 8800 and the assembly line to add to Assembly Lines/processAdd.
6. The userpassword / erpassword attribute is a binary attribute.  It is base 64 encoded by TIM for transmission in the XML document to IDI and then decoded by IDI to transform it back into a byte array. To configure the event handler to perform this decoding add erPassword to the Binary Attributes list in the configuration screen for the handler.
7. Click the run button on the Event Handler.
   

1. In the PersonAdd tab change the mode from Add Only to Update.
2. In the Link Criteria tab add a new Link Criteria, building the link criteria with the custom script:
   

   var dn = work.getString("$dn");
   var end = dn.indexOf(",");
   var filter = dn.substring(2, end);
   ret.filter = filter;

   This is required to strip the first two characters "er" from the user id attribute.
3. In the Event Handler Configuration tab set the Assembly Line for Modify to processAdd.
4. Restart the Event Handler.
5. In the TIM user interface test the change by submitting a change to the account created in the first part of the example.
   

1. Add a new Assembly Line and call it processDelete.
2. Add a new connector to the processDelete assembly line, set it to be of type ibmdi.JNDI, and set it to operate in Delete mode.  
3. In the configuration tab of the connector set the configuration details to be the same as the connector in the processAdd assembly line.
4. In the Link Criteria tab add a new Link Criteria, building the link criteria with the same custom script described above for modify requests.
5. Stop the event listener, if it is still running, and close the event handler tab if it is still open.
6. Open the event handler tab again and in the Configuration panel set the Assembly Line for Delete to processDelete.
7. Restart the Event Handler.
8. In the TIM user interface test the change by submitting a delete request for the account created in the first part of the example.

        ret.filter = "member=uid=" + work.getString("eruid") + " ," + AccountConnector.getConnectorParam("ldapSearchBase");

        work.addAttributeValue("testgroupmember", work.getString("groupDn"));

1. Create a new IDI Connector of type BTreeObjectDB in lookup mode.  Set the File Name to be credentials.db.  Set the Key Value Attribute to be 'username'.
   
2. In the DSMLv2 event handler set the Auth Connector to be the Connector created in step 1.
   

AccountConnector.connector.setParam("ldapSearchFilter", work.getString("dsml.filter"));