Chapter 7 Configuring User Actions

This chapter details how to add custom tasks to the Waveset Administrator Interface and configure user actions that you can execute from two areas of the interface:

• User Account Search Results page

• User applet on the Accounts page

To add a custom task, you must edit an existing TaskDefinition You can use the Identity Manager IDE to view and edit task definitions. Instructions for installing and configuring the Identity Manager IDE are provided on https://identitymanageride.dev.java.net.

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

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

2. Create a new AdminGroup (capability) for the task

3. 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 7–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 Waveset 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 Identity Manager IDE 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 7–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.

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 7–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>

Configuring User Actions

You must configure definitions for the buttons and actions menu selections that initiate custom actions. Definitions for the buttons and actions menu items that appear on the User Account Search Results and Accounts pages are contained in the User Actions Configuration configuration object.

Do not directly edit the User Actions Configuration object. Rather, best practice for configuring user actions is to:

• Copy the User Actions Configuration configuration object into a new configuration object.

• Modify the System Configuration object to point to the new configuration object.

To Configure User Actions

1. Copy the User Actions Configuration configuration object into a new XML file.

2. Change the name of the new object to My User Actions Configuration.

3. Make any desired modifications to My User Actions Configuration.

4. Import the XML file into Waveset from the Import Exchange File page

5. Modify SystemConfiguration to change the userActionsConfigMapping attribute’s value to My User Actions Configuration

   The configuration object consists of these configuration sections.

   Attribute	Description
   findUsersButtons	Contains a list of button definitions for the Administrator Interface User Account Search Results page.
   userApplet.userMenu	Contains a list of menu item definitions for the user actions menu. This menu displays when you right-click a user in the applet on the Administrator Interface Accounts page.
   userApplet.organizationMenu	Contains a list of menu item definitions for the organization actions menu. This menu displays when you right-click an organization in the applet on the Accounts page.

   Each section contains a list of user actions to display in the interface. The button and menu configuration items have the same basic properties. Both include several extensions unique to the interface.

   The following excerpt is an example of the user action configuration customized to add the Change Organization task to each list.

   <?xml version=’1.0’ encoding=’UTF-8’?> <!DOCTYPE Waveset PUBLIC ’waveset.dtd’ ’waveset.dtd’> <Waveset> <Configuration name=’My User Actions Configuration’> <Extension> <Object> <!-- Buttons for the find users results page. --> <Attribute name=’findUsersButtons’> <List> <Object> <Attribute name=’textKey’ value=’UI_NEW_LABEL’ /> <Attribute name=’commandName’ value=’New’ /> <Attribute name=’requiredPermission’> <Object> <Attribute name=’objectType’ value=’User’ /> <Attribute name=’rights’ value=’Create’ /> </Object> </Attribute> <Attribute name=’alwaysDisplay’ value=’true’ /> </Object> ... <Object> <Attribute name=’textKey’ value=’UI_CHANGE_ORGANIZATIONS_LABEL’ /> <Attribute name=’commandName’ value=’Change Organizations’ /> </Object> </List> </Attribute> <Attribute name=’userApplet’> <Object> <!-- The menu to display when a user is selected. --> <Attribute name=’userMenu’> <List> <Object> <Attribute name=’textKey’ value=’UI_ACCT_JAVA_MENU_NEW_ORG’ /> <Attribute name=’commandName’ value=’New Organization’ /> <Attribute name=’requiredPermission’> <Object> <Attribute name=’objectType’ value=’ObjectGroup’ /> <Attribute name=’rights’ value=’Create’ /> </Object> </Attribute> </Object> ... <Object> <Attribute name=’separator’ value=’separator’ /> </Object> <Object> <Attribute name=’textKey’ value=’UI_CHANGE_ORGANIZATIONS_MENU_LABEL’ /> <Attribute name=’commandName’ value=’Change Organizations’ /> </Object> </List> </Attribute> <!-- The menu to display when an organization is selected. --> <Attribute name=’organizationMenu’> <List> <Object> <Attribute name=’textKey’ value=’UI_ACCT_JAVA_MENU_NEW_JUNCTION’ /> <Attribute name=’commandName’ value=’New Directory Junction’ /> <Attribute name=’requiredPermission’> <Object> <Attribute name=’objectType’ value=’ObjectGroup’ /> <Attribute name=’rights’ value=’Create’ /> </Object> </Attribute> <Attribute name=’orgTypes’ value=’normal,dynamic’ /> </Object> ... <Object> <Attribute name=’separator’ value=’separator’ /> </Object> <Object> <Attribute name=’textKey’ value=’UI_CHANGE_ORGANIZATIONS_MENU_LABEL’ /> <Attribute name=’commandName’ value=’Change Organizations’ /> </Object> </List> </Attribute> </Object> </Attribute> </Object> </Extension> <MemberObjectGroups> <ObjectRef type=’ObjectGroup’ name=’All’/> </MemberObjectGroups> </Configuration> </Waveset>

   User action definitions support these core attributes.

   Attribute	Description
   textKey	Message catalog key for the text of the button or menu item.
   commandName	Name of the command to execute. This can be a command that is natively supported (such as New or Delete User), or the name of a TaskDefinition to execute.
   requiredPermission.objectType	Type of object that the rights are required on in order to display this item. This is applicable only for natively supported commands. Task Definitions should use AuthTypes for controlling access.
   requiredPermission.rights	Comma-separated list of Right names required on the specified objectType to display this item. This is applicable only for natively supported commands. Task Definitions should use AuthTypes for controlling access.
   alwaysDisplay	Optional. Specifies whether to always display this button. If set to a value of true, the button is displayed even if user search returns no results. The default value for this attribute is false. Applies to findUsersButtons section only.

   User actions definitions in the userApplet section also support the attributes in the following table.

   Attribute	Description
   orgTypes	Comma-separated list of organization types for which to display the item in the organization menu. Possible values are normal, dynamic, and virtual for normal organizations, dynamic organizations, and virtual organizations, respectively.  If this attribute is not specified, the menu item is displayed for all organization types.
   separator	Special item in the format <Object><Attribute name=’separator’ value=’separator’/></Object>. Separators are displayed as horizontal bars in the Administrator Interface menus, and cannot be selected.