Sun Identity Manager Deployment Guide

Adding Custom Tasks

Follow these general steps to add custom tasks:

Set up authorization for the task
Add the task to the repository

Setting Up Custom Task Authorization

Typically, you set authorization for custom tasks to restrict access to the task to a certain set of administrators.

To Set Up Authorization

Add a new authorization type (AuthType) to the repository for the task

Create a new AdminGroup (capability) for the task

Grant the new capability to one or more administrators

Step 1: Create an AuthType

The new authorization type you create should extend the existing TaskDefinition, TaskInstance, and TaskTemplate AuthTypes. To add the authorization type, edit the Authorization Types Configuration object in the repository and add a new authorization type element for your task.

Use the <AuthType> element to create a new authorization type. This element has one required property: name. The example below displays the correct syntax for an <AuthType> element.

After creating the authorization type, you must edit the Authorization Types Configuration object in the repository, and add the new <AuthType> element.

The following example shows how to add a custom task to move multiple users into a new organization.

Example 6–1 Moving Multiple Users into a New Organization

<Configuration name=’AuthorizationTypes’> 
   <Extension> 
      <AuthTypes> 
         <AuthType name=’Move User’ extends=’TaskDefinition,TaskInstance,TaskTemplate’/> 
      </AuthTypes> 
   </Extension> 
</Configuration>

Step 2: Create an AdminGroup

Next, create an AdminGroup that grants Right.VIEW for the newly created AuthType. To do this, you must create an XML file with the new administrator group, and then import it into the Identity Manager repository.

<?xml version=’1.0’ encoding=’UTF-8’?> 
<!DOCTYPE Waveset PUBLIC ’waveset.dtd’ ’waveset.dtd’> 
<Waveset> 
   <AdminGroup name=’Move User’ protected=’true’ description=’UI_ADMINGROUP_MOVE_USER_DESCRIPTION’ 
displayName=’UI_ADMINGROUP_MOVE_USER’ > 
      <Permissions> 
         <Permission type=’Move User’ rights=’View’/> 
      </Permissions> 
      <MemberObjectGroups> 
         <ObjectRef type=’ObjectGroup’ id=’#ID#All’ name=’All’/> 
      </MemberObjectGroups> 
   </AdminGroup> 
</Waveset>

The displayName and description attributes are message catalog keys. If these are not found in a message catalog, they are displayed as they are found in the attributes. If message catalog keys are used, you must add the messages either into WPMessages.properties or a custom message catalog.

Step 3: Grant Capabilities to Administrators

Finally, you must grant administrators access to execute the newly defined task. You can accomplish this in one of two ways:

Directly assign the new capability.
Add the new capability to an Admin Role (either directly or by using a capabilities rule), and then assign it.

Adding a Task to the Repository

After you set up task authorization, you can add the task to the repository. The task is a typical TaskDefinition that can be defined through the Sun Identity Manager Integrated Development Environment or imported as XML. For example, a task to change the organization for multiple users would resemble the following example (which is included in the samples directory).

Example 6–2 Changing the Organization for Multiple Users

<?xml version=’1.0’ encoding=’UTF-8’?> 
<!DOCTYPE TaskDefinition PUBLIC ’waveset.dtd’ ’waveset.dtd’> 
<!-- MemberObjectGroups="#ID#Top" authType="Move User" name="Change Organizations" 
taskType="Workflow" visibility="runschedule"--> 
<TaskDefinition authType=’MoveUser’ name=’Change Organizations’ taskType=’Workflow’ 
executor=’com.waveset.workflow.WorkflowExecutor’ suspendable=’true’ syncControlAllowed=’true’ execMode=’sync’ 
execLimit=’0’ resultLimit=’0’ resultOption=’delete’ visibility=’runschedule’ progressInterval=’0’> 
   <Form name=’Change Organization Form’ title=’Change Organization Form’> 
      <Display class=’EditForm’/> 
      <Include>
         <ObjectRef type=’UserForm’ name=’User Library’/> 
         <ObjectRef type=’UserForm’ name=’Organization Library’/> 
      </Include> 
      <FieldRef name=’namesList’/> 
      <FieldRef name=’orgsList’/> 
      <FieldRef name=’waveset.organization’/> 
   </Form> 
   <Extension> 
      <WFProcess name=’Change Organizations’ title=’Change Organizations’> 
         <Variable name=’waveset.organization’/> 
         <Variable name=’userObjectIds’ input=’true’> 
            <Comments>The names of the accounts to change the organization on.</Comments> 
         </Variable> 
         <Activity id=’0’ name=’start’> 
            <ReportTitle> 
               <s>start</s> 
            </ReportTitle> 
            <Transition to=’Process Org Moves’/> 
         </Activity> 
         <Activity id=’1’ name=’Process Org Moves’> 
            <Action id=’0’ process=’Move User’> 
               <Iterate for=’currentAccount’ in=’userObjectIds’/> 
               <Argument name=’userId’ value=’$(currentAccount)’/> 
               <Argument name=’organizationId’ value=’$(waveset.organization)’/> 
             </Action> 
             <Transition to=’end’/> 
         </Activity> 
         <Activity id=’2’ name=’end’/> 
      </WFProcess> 
   </Extension> 
   <MemberObjectGroups> 
      <ObjectRef type=’ObjectGroup’ id=’#ID#Top’ name=’Top’/> 
   </MemberObjectGroups> 
</TaskDefinition>

Note these features of the preceding example:

The task’s authType attribute is set to Move User. This will restrict access to this task to users that are assigned the capability to execute this authorization type.
The form contains FieldRefs to namesList and orgsList. These fields are defined in the User Library and Organization Library, respectively. Including these fields will display lists of the names of all selected users and all selected organizations. For potentially dangerous tasks, you should include one or both of these fields so the user is aware of the potential effects of running the task.
The task has an input variable named userObjectIds. This variable contains a list of the names or IDs of the users selected in the User Account Search Results page or in the user applet on the Accounts page. Iterate over this variable to perform the desired action on all selected users.

The following table lists the variables that are available for input to the task.

Table 6–1 Task Variables


Variable	Description
`userObjectIds`	List of IDs of the selected users. Available from the User Account Search Results and Accounts pages. When invoked from the User Account Search Results page, this list contains the names of the selected users.
`userNames`	List of names of the selected users. Available from the User Account Search Results and Accounts pages.
`orgObjectIds`	A List of IDs of the selected organizations. Available only from the Accounts page.
`orgNames`	A List of names of the selected organizations. Available only from the Accounts page.

To enable this workflow, you must also add to the repository a sub-process to change a user’s organization, as shown in the following example.

Example 6–3 Changing a User’s Organization

<?xml version=’1.0’ encoding=’UTF-8’?> 
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’> 
<!-- MemberObjectGroups="#ID#Top" configType="WFProcess" name="Move User"--> 
<Configuration name=’Move User’ createDate=’1083353996807’> 
   <Extension> 
      <WFProcess name=’Move User’ title=’Move User’> 
         <Variable name=’userId’ input=’true’> 
            <Comments>The accountId of the user to move.</Comments> 
         </Variable> 
         <Variable name=’organizationId’ input=’true’> 
            <Comments>The ID of the organization to move the user into.</Comments> 
         </Variable> 
         <Activity id=’0’ name=’Start’> 
            <Transition to=’Update Organization’/> 
         </Activity> 
         <Activity id=’1’ name=’Update Organization’> 
            <Action id=’0’ process=’Update User View’> 
               <Argument name=’accountId’ value=’$(userId)’/> 
               <Argument name=’updates’> 
                  <map> 
                     <s>waveset.organization</s> 
                     <ref>organizationId</ref> 
                  </map> 
               </Argument> 
            </Action> 
            <Transition to=’End’/> 
         </Activity> 
         <Activity id=’2’ name=’End’/> 
      </WFProcess> 
   </Extension> 
   <MemberObjectGroups> 
      <ObjectRef type=’ObjectGroup’ id=’#ID#Top’ name=’Top’/> 
   </MemberObjectGroups> 
</Configuration>