Recommended prerequisites

1. Read "Running the Application API Examples" found in the IBM Tivoli Identity Manager Information Center
2. Read "Application API" found in the IBM Tivoli Identity Manager installation directory
3. Read Introduction to Tivoli Identity Manager API development
4. Read Integrating Tivoli Identity Manager with WebSphere® Portal using a WSAD development environment: Set-up and Configuration Tips

Back to top

Overview

The Entitlement Request scenario gives managers in the Tivoli Identity Manager provisioning platform a way to approve requests without accessing the Tivoli Identity Manager Web console. For example, in an enterprise where the business process requires approval when you enter a user into the system. (Entitlement and approval business logic is implemented in ITIM using the ITIM workflow. The code snippet in this article is tightly bound with Tivoli Identity Manager workflow. Please see the ITIM documentation for further information on developing a workflow.) The My Personal Information scenario gives employees a way to update their information in ITIM without accessing the ITIM web console. scenario gives employees a way to update their information in ITIM without accessing the Tivoli Identity Manager Web console. This might be the case for an enterprise's internal customized portal application that provides employees with a variety of internal portlets with provisioning capabilities, such as self-registration, or user account management.

The Entitlement Portlet and the My Personal Information Portlet are basic user provisioning portlets that are useful in a company's portal. The Entitlement Request Portlet and My Account Information Portlet are assumed to have the look and feel of an interface as shown in Figure 1 and Figure 2.

The portlet shown in Figure 1 gives managers a way to approve entitlement requests. In this portlet, managers can optionally assign a new role or multiple roles to the new employee during the approval process.

Other user provisioning activities that might require management approval are adding a new employee in the company's system, or moving an employee from one department to another. These provisioning activities can be implemented in a portlet similar to the Entitlement Request Portlet described in this article.

Figure 2 shows a portlet that enables employees to update their personal information (that is, their home address, office address, first name, last name, etc.).

The general flow of the sequence of activities in the Entitlement Request Portlet and the My Information Portlet is:

1. Entitlement Request Portlet
   1. Retrieve the requests to be approved
   2. Retrieve roles available for a request (department-specific)
   3. Make the approval/rejection
   4. Assign chosen role to employee
2. My Information Portlet
   1. Update employee personal information

Back to top

Entitlement Request Portlet

1. Retrieve the requests to be approved

The following snippet of code shows an example of how to retrieve requests that require a manager's approval.

				 
	Account account	= getAccount(ACCOUNTFILTER, userID, platform, subject);
	//ACCOUNTFILTER could be "eruid"
	AccountMO accountMO = new AccountMO(platform, subject, account.getDistinguishedName());
	HumanResourceMO hrMO = new HumanResourceMO(platform, subject, accountMO);
	
	//this will return a collection of request
	Collection requests= hrMO.getAssignments();
	
	//use an iterator to retrieve the requests and store them in the session bean
	Iterator requestIT = requests.iterator();
	WorkflowAssignmentMO wfaMO=null;
	int index=0;
	while (requestIT.hasNext()){
	
		wfaMO = (WorkflowAssignmentMO) requestIT.next();
	sessionBean.storeRequest(wfaMO.getData(),index);
	sessionBean.setEmployeeName(wfaMO.getData().getRequestee(), index);
		System.out.println("Requests id: " + wfaMO.getID());	
		index ++;		
	}
	.
	.
	

First, based on the logon user ID of the manager, the manager's Tivoli Identity Manager account is retrieved using the method described in the article Introduction to developing with Tivoli Identity Manager APIs. The retrieved account object is used as the parameter to initialize a managed account object called AccountMO.

Next, the HumanResourceMO object is initialized in order to manage a human resource account participating in a workflow. A collection of WorkflowAssignmentMO objects can be obtained from the HumanResourceMO object. This is the list of requests waiting for the manager's approval. The details of each request come from the Assignment object contained in the WorkflowAssignmentMO object (for example, request ID, name of the manager, name of the employee).

2. Retrieving roles available for a request (department-specific)

The next step is to get the available roles for the department. In Tivoli Identify Manager, a department is also referred to as an “organization unit” and this is reflected in the Tivoli Identify Manager API's OrganizationalContainerMO object initialization.

First, let's take a look at the getRole() method in Figure 4. This is similar to other managed object searches in Tivoli Identify Manage API as described in the article Introduction to developing with Tivoli Identity Manager APIs.

				 
	public Collection getRole(DistinguishedName dn, PlatformContext platform,Subject subject)
	{
		Collection roles = null;
		try{
			SearchMO searchMO = new SearchMO(platform,subject);
			searchMO.setCategory(ObjectProfileCategory.ROLE);
			OrganizationalContainerMO ocmo = new OrganizationalContainerMO (platform,subject,dn);		
			searchMO.setContext(ocmo);
			searchMO.setProfileName(PROFILENAME);	
	
			//Filter can be set to attribute of "errolename"
			searchMO.setFilter("\"(errolename=*)\"");
	
			roles = searchMO.execute().getResults();
				
			if (roles.size() == 0)
				System.out.println("No roles found");	
		}
		catch(RemoteException e){
			e.printStackTrace();
		}
		catch(ApplicationException e){
			e.printStackTrace();
		}
	
		return roles;
	}
	

Next, invoke the getRole() method by providing the distinguished name of the department to which the manager belongs. It will return a collection of roles available for that department.

				 
	String roleFilter = "errolename=*";
	//managerDN  is the distinguished name of the department that the manager belongs to
	Collection roles = getRole(managerDN, platform, subject);
	

Use an iterator to iterate through the collection to retrieve each role and store it, along with its details, in a Role object.

				 	
	Iterator rolesIT = roles.iterator();
	index=0;
	while(rolesIT.hasNext()){
	
	    Role role= (Role) rolesIT.next();
	    //Store the roles available in the session bean
	    sessionBean.setRoleAvail(role.getName(), index);
	    sessionBean.setRoleDn(role.getDistinguishedName().getAsString(), index);
	    index++;
	}
	.
	.
	

3. Make the approval or rejection

Based on the manager's selection for each request, an ActivityResult object, a class that holds the result of an activity, is created with the selected state (approved or rejected) to complete the approval process using the WorkflowAssignmentMO object.

				 	
	ActivityResult ar = null;
	if(managerSelect.equals("Approve")){	
	
	          ar = new ActivityResult( ActivityResult.STATUS_COMPLETE, ActivityResult.APPROVED);
	}
	else if (managerSelect.equals("Reject")) {
	          ar = new ActivityResult( ActivityResult.STATUS_COMPLETE, ActivityResult.REJECTED);
	}
	try  {
		wfaMO.complete(ar);
	}
	catch(Exception e){
		e.printStackTrace();
	}	
	.
	.
	

4. Assign chosen role to employee

If the manager approves the request, the chosen role is assigned to the employee. This can be achieved by first using the getPerson() method to retrieve the Person object of the employee. Then, the distinguished name of the role chosen, which is stored in the session bean in Step 2, is retrieved to create the DistinguishedName object. The DistinguishedName object is a unique key identifying each role. The DistinguishedName object is then used to create a RoleMO object, which is later used to manage organizational roles. Last, a request must be submitted to Tivoli Identity Manager to add the employee as a member to the specified role to complete the role assignment. Thus, a PersonMO object must be created from the employee's distinguished name and be passed as a parameter in the addMember() method of the RoleMO object to create the Request object that is sent to Tivoli Identity Manager.

				 	
	String personFilter="cn="+sessionBean.getEmployeeName(index);
	//eg. "cn=Joe Smith"
	Person employee = TIMService.getPerson( personFilter, platform, subject);
							  						  
	String roleDN= sessionBean.getRoleDn(index);
	DistinguishedName dnRoleName = new DistinguishedName (roleDN);
	RoleMO roleMO = new RoleMO(platform,subject, dnRoleName);
	
	//create a PersonMO object
	PersonMO personMO = new PersonMO(platform, subject, employee.getDistinguishedName());
				
	try {
	Request chgRoleRequest = roleMO.addMember(personMO,null);   
	System.out.println("Add Role Request has been submitted as " + 
	     chgRoleRequest.getID());
	}
	catch(Exception e){
		e.printStackTrace();
	}
	.
	.
	

Back to top

My Information Portlet

1. Update employee personal information

To update personal information that resides in the Employee Directory, an AttributeValue object must first be created to save each new piece of personal information. Each AttributeValue object is then set as a personal attribute using the setAttribute() method of the Person object. The Person object, the employee in this case, is retrieved using the getPerson() method, which takes the user ID of the employee as a search parameter.

To complete the update, a PersonMO object must first be created for the employee using the employee's DistinguishedName. In this scenario, the DistinguishedName is a unique key identifying each person. Then a request to Tivoli Identity Manager to update the personal information can be generated by passing in the Person object (the employee) as a parameter into the update() method of the PersonMO object.

				 			
	String filter = "uid=" + user;
	Person employee	= null;
	//filter should look like this:  employeeNumber=12345
	employee = TIMService.getPerson(filter,platform, subject);
		
	if (employee != null) {
	AttributeValue av=new AttributeValue("givenname", sessionBean.getFirstname());
	employee.setAttribute(av);
	av = new AttributeValue("sn", sessionBean.getLastname());
		employee.setAttribute(av);
		
		//and so on for the rest of the other text field, such as  job title, etc.
		.
		.
	}
	try {
		//PersonManager mgr = new PersonManager(platform, subject);
		PersonMO employeeMO = new PersonMO(platform, subject, employee.getDistinguishedName()); 
					
		if (employeeMO != null) 
		{ 
		
		// commit change immediately
		Request re = employeeMO.update(employee, null);				
		System.out.println("Updated TIM Person Info. RequestID=" + re.getID());
		}
	}
	
	catch (RemoteException re) {
	System.out.println(re.getMessage());
	}
	catch (AuthorizationException ae) {
	System.out.println(ae.getMessage());
	}
	catch (ApplicationException ae) {
		System.out.println(ae.getMessage());
	}	
	.
	.
	

Back to top

Conclusion

In this article, you learned how to invoke the IBM Tivoli Identity Manager API from a remote application to retrieve and respond to approval requests assigned to a user, to add a user to a role, and how employees can update personal information.

Resources

• The article Introduction to developing with Tivoli Identity Manager API's developerWorks, October 2005) is a step-by-step guide on developing a customized Password Management Portlet that will change the password on all of a user's accounts in a system environment, and thereby demonstrate the usage of some common Tivoli Identity Manager API's.
  
  
• The article Integrating Tivoli Identity Manager with WebSphere Portal using a WSAD Development Environment: Set-up and Configuration Tips (developerWorks, March 2006) is a step-by-step guide necessary to configure your portal development environment using IBM WebSphere Studio Application Development to interface with the IBM Tivoli Identity Manager APIs.
  
  
• Tivoli Software Information Center API Documentation
  
  

About the author

Janet joined IBM full time after graduating with a Bachelor of Applied Science in Computer Engineering degree from the University of Waterloo. She has previously worked at various IBM software functions within the Toronto IBM Software lab, including the DB2 Regression team and the Java Just-in-Time Compiler Development team. Janet is currently a part of Software Group Strategy, Scenario Analysis Lab, where she is implementing a customer-based scenario named the Employee Workplace, using various IBM products such as DB2 Content Manager, DB2 Document Manager, DB2 Records Manager, WebSphere Information Integrator OmniFind Edition, and WebSphere Portal.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Overview
• Entitlement Request Portlet
• My Information Portlet
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Tivoli on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers