ITIM Extensions

1. ITIM Extensions November 2007 Jeff Dare

2. Extending ITIM • ITIM provides large amount of “out-of-the-box” functionality • However, many customers have IDM requirements that cannot be met by ITIM alone • ITIM provides many user-customizable elements • If this is not sufficient then you can extend ITIM using JavaScript and/or Java programming

3. Getting Started…. • If you don’t “do Java” then make friends with someone who does….. • What the hell does all that stuff mean ? • What was wrong with good old procedural languages like C, Pascal, FORTRAN and Assembler/370 ? • Why doesn’t JavaScript look like Java ?

4. Documentation – Part 1 • ITIM 4.5 Defining and Extending Workflows with JavaScript and Application Extensions by David Saucier • ITIM 4.6 Extending Workflows with Java White paper by Ori Pomerantz March 2006 • ITIM 4.6 Online Help Files • <ITIM_HOME>\extensions\examples

5. Documentation – Part 2 • SG24-7242 IDM Advanced Design Guide for ITIM • ITIM 4.5.1 Policy and Organisation Administration Guide • Extending ITIM course

6. Editting JavaScript via Browser • By default, cut and paste operations are not available between ITIM applets and other applications • To enable, must run Java policytool on your PC and add entry like: grant codeBase "http://<itim-server-host-name>/enrole/*" { permission java.awt.AWTPermission "accessClipboard"; }; • Beware of WebSEAL timeouts as the ITIM editors are mostly applets….

7. Using JavaScript in Provisioning Policies • Used to define provisioning parameters. • May be written using the following built-in objects: • subject • service • Parameters.eruid • context • May be written using the following built-in functions: • subject.getProperty (String rowAttrName) • PersonSearch.searchByFilter (String profileName, String filter, [int scope]) • ServiceSearch.searchByFilter (String filter, [int scope]) • Enrole.toGeneralizedTime (Date date)

8. JavaScript Example • Obtaining an attribute value: {var empid = subject.getProperty("employeenumber"); • Verify optional attribute has a value: if ((empid !=null) && (empid.length > 0)){ empid = empid[0]; }else{ empid = ""; } • Return the attribute value: return empid;}

9. Returning Multiple Values Technote (FAQ)Problem Sometimes it is necessary to create defaults, in an ITIM provisioning policy, that will use javascript to dynamically return multiple values to a multi-valued attribute. Solution In order to have javascript return multiple values, in an ITIM provisioning policy, there must be a javascript function that creates/returns an array. Here is an example: {function getVals() {var values = new Array();values[0] = parameters.eruid[0];values[1] = 'other';return values;}getVals();}

10. Entitlement Workflows • Specify the process to get approval for account creation. • Can end with the request either accepted or rejected. • Specified in the entitlements of the Provisioning Policy.

11. Extending Workflow Elements • Most Workflow Elements have postscripts that can be filled with JavaScript. • Some Elements can also be modified in other ways: • Custom participant • Notification • Action Text

12. Custom Participants • Several Workflow Elements have participants. • Custom participants are determined using a script. • In the following example, one approver is chosen during working hours, another during other times.

13. Time Based Custom Participant var now = new Date(); var hour = now.getHours(); var day = now.getDay(); var approverName; if ((day == 0) || (day == 6) || (hour < 8) || (hour > 16)) { approverName = "Alice Smith"; } else { approverName = "John Doe"; }

14. Time Based Custom Participant - 2 Enrole.log("", "Day:" + day + " Hour:" + hour + " Approver:" + approverName); var personSearch = new PersonSearch(); var searchResults = personSearch.searchByFilter("Person", "(cn=" + approverName + ")",2); var approverDN = searchResults[0].dn; return new Participant(ParticipantType.USER, approverDN);

15. Parameters/Relevant Data - 1 • Each workflow has access to a set of Relevant Data that can be read or changed from within a workflow script • Some Relevant Data items are fixed according to the workflow specifics e.g input and output parameters • You can add your own Relevant Data items to the workflow using get() and set()

16. Parameters/Relevant Data - 2 • Relevant Data is specific to each process • Examples: ou.set(“engineering”); var dn = subjectDN.get(); • Can be used to pass data between nodes in a workflow and to update objects accessible to the workflow

17. Parameters/Relevant Data - 3 • Parameters of the Workflow: • Input Parameters • Output Parameters • Relevant Data

18. Parameters/Relevant Data - 4 • I once managed to delete an Input Parameter from one of the system entities lifecycle workflows, and was unable to manually restore it • I ended up having to restore a backup of the operation so be careful !

19. Using Parameters in JavaScript var acct = entity.get(); if (acct.getProperty("erunixshell")[0] == "/bin/sh") { acct.setProperty("erunixshell", new Array ("/bin/bash")); } entity.set(acct);

20. Listing Owner Information Run a script to display the owner attributes: var acct_owner = owner.get(); var props = acct_owner.getPropertyNames(); for(var i=0; i<props.length; i++) { var values = acct_owner.getProperty(props[i]); var valString = ""; for(var j=0; j<values.length; j++) valString += values[j] + ","; Enrole.log("script", props[i] + " -> " + valString); }

21. Owner Information • Use the viewer script to translate the log to HTML. • This is the relevant portion of msg.log:

22. Script to Obtain the Organizational Unit var acct_owner = owner.get(); var parentDN = acct_owner.getProperty("erparent")[0]; // get the first part of the DN, the erglobalid var parentID = parentDN.substring(0, parentDN.indexOf(",")); // find the parent var ouSearch = new ContainerSearch(); var results = ouSearch.searchByFilter("Organizational Unit", "(" + parentID + ")", 2); var ou = results[0];

23. Operation Workflows • Modify the behavior of IBM Tivoli Identity Manager during an operation: • Add • Modify • ChangePassword • Delete • Suspend • Restore • Can be configured at the Entity or Entity Type level.

24. Process Workflow Extensions • process object is exposed to workflow scripts. Some of the available methods are show below. • process.auditEvent • process.comment • process.description • process.getActivity • process.getParent • process.requestorId • process.requestorName • process.requestorType • process.started • process.id

25. Activity Workflow Extensions • activity object is exposed to workflow scripts. Some of the available methods are show below. • activity.auditEvent • activity.id • activity.name • activity.setResult • activity.started • activity.type

26. Notification Factories • Java code to customise notifications of workflow activities • Excellent examples included in extensions sub-directory

27. Generating Messages • Enrole.log(“Component”,”message”) • Generates an error message to the ITIM msg.log file • process.audit(“message”) • Generates message to process-level audit log • activity.audit(“message”) • Generates message to activity level audit log

28. FESI Extensions - 1 • ITIM JavaScript interpreter can be extended using Java • To implement a new function that will be available to JavaScript within ITIM, perform the steps on the next pages.

29. FESI Extensions - 2 • Create a new Java class that implements the interface FESI.Extensions.Extension • Within this class, create an inner class that extends FESI.Data.BuiltInFunctionObject • This class needs two methods – a class that call the constructor of the superclass and the function that implements the JavaScript function called CallFunction

30. FESI Extensions - 3 • In the public class, write a function called initializeExtension that creates a new object of the inner class and registers it as a property of the global object. • Register the public class with FESI by editting the file <ITIM_HOME>/data/fesiextensions.properties

31. FESI Extensions - 4 • package examples.javascript; • import FESI.jslib.*; • import java.util.*; • import com.ibm.itim.common.*; • import com.ibm.itim.logging.*; • import com.ibm.itim.dataservices.model.*; • import com.ibm.itim.dataservices.model.domain.*; • import com.ibm.itim.dataservices.dit.*;

32. FESI Extensions - 5 • public Object doCall(JSObject thisObject, Object[] args) { • if (args.length == 1) { • RoleSearch rs = new RoleSearch(); • RoleEntity entity = null; • try { • entity = rs.lookup(new DistinguishedName((String) args[0])); • } catch (ModelCommunicationException e) { • e.printStackTrace(); • } catch (ObjectNotFoundException e) { • e.printStackTrace(); • } • if (entity != null) { • return entity.getDirectoryObject().getName(); • } • } • return null; • } • } • }

33. FESI Extensions - 6 • public class GetRoleNameFunctionExtension implements JSExtension { • public void initializeExtension(JSGlobalObject go) throws JSException { • // Register the getRoleName function. • go.setMember("getrolename", new GetRoleNameFunction()); • } • /** • * Provides the increment function business logic. • */ • private class GetRoleNameFunction extends JSFunctionAdapter {

34. Application Extensions • Can extend ITIM workflows by writing custom Java application extensions and adding them to workflows using the Extension node • Need to update XML file to register the extension and add the new Java class(es) to the CLASSPATH of the JVM running ITIM • Can add input and output parameters to the extnsion node to match those required by the Java extension

35. Import/Export Facility • Can backup workflows using Import/Export facility • Calculates (obvious) dependencies and exports these automatically • Try not to have more than 50 objects to import as this can cause difficulties when importing to another ITIM system

36. Failures • If your script fails for some reason, check the Completed Items and extract what information you can • You will probably need to go to the msg.log to get details of what has occurred • Depending on the severity of the failure the process might be terminated, or the activity might be set as failed

37. Further Information • Contact Details Jeff Dare jeff.dare@senetas.com 0400 648 480 • Web Site: www.senetas.com