Role Owner Approvals

In TIM 5.0 the Role Owner can now be the participant of an Approval activity. Out of the box there are two new workflow extensions with regards to handling role changes for a given person.

Role Owner Approval Workflow Extensions

• approveRolesByOwner(Person person)
  • Person person
  - Cannot be null. Will cause activity to fail because of invalid data.
  This workflow extension takes a person as an input parameter. If the person has new roles found (determined by the javascript: person.getNewRoles()), approvals will be generated for those roles and sent to the role owners. The approval process cannot be customized and so the participant is always the Role Owner. The roles cannot be customized and will always be the new roles on the person.
• approveRolesWithOperation(Person person, List rolelist, String approvalOperationName)
  • Person person
  - Cannot be null. Will cause activity to fail because of invalid data.
  • List rolelist
  - Can be null. If null, roles to approve will be pulled off the person via the javascript: person.getNewRoles(). A new list of roles can be manually set to the rolelist by writing the appropriate script within a script node prior to the Role Owner Approval Workflow Extension node. For instance, the following script could be used to set a new role to the rolelist:

  		<script>
  		var roles = (new RoleSearch()).searchByName("roleName");
  		if (roles.length > 0) {
  		rolelist.set(roles);
  		}
  		</script>
  		

  Here, roleName is the name of an existing role.
  • String approvalOperationName
  - Can be null. If null, the default simple approval operation (which has the role owner as the participant) will be used.
  This workflow extension takes a person, role list, and approval operation name as input parameters. The person's new roles will start the specified approval operation name for each role. If a role list passed to the extension and is not null while having roles in it, approvals will only be generated for those roles in the list rather than using person.getNewRoles().
• Note: When one or more role approval requests are rejected by the role owner, then the respective roles shall not be added to the person, but the person operation will be continued in the usual manner.

Role Owner approval during a Person Create or Modify

1. Simple role owner approval for all new roles
2. Customized role owner approval process for all new roles
3. Additional customizations that could be made to skip the approval process, when the new roles have no owner defined.

This example builds upon the first example above but the use case is slightly modified.

Use case: Given a person's new roles (added during person add or person modify), role owner approvals need to be generated for each of those new roles provided those new roles have owners defined. However, the role owner approval process needs to be customized rather than using the simple approval process defined out of the box. If the owner is not defined for the newly added role, then the participant resolution fails and the approval request goes to System Administrators. After executing the below steps, kindly follow the steps mentioned under the third heading listed above, if you need to skip the approval process by the System Administrators, in the absence of a role owner.

Changes are required to the person add and person modify operations (Configure System > Manage Operations) highlighted below.

Both the person add and person modify operations will require the same extension activity dragged in before the CREATEPERSON activity or MODIFYPERSON activity.

First modify the person add operation by opening the operation in the workflow designer. Drag in a new EXTENSION activity. Connect transitions between the START, EXTENSION, and CREATEPERSON activities as show below. The extension to select is approveRolesWithOperation(Person person, List rolelist, String approvalOperationName). Finally map the person relevant data item to the person input parameter and person output parameter.

Click on Search Relevant Data.

Add a rolelist relevant data item.

Add a customApprovalOperationName relevant data item with a default value of My Custom Role Approval. This name could be any global operation name that has been setup for being a custom role approval operation (shown later in this example).

Final relevant data item list after adding rolelist and customApprovalOperationName.

The final extension activity after mapping all relevant data items. Click OK to save the activity and click OK to save the person add operation.

Modify the person modify operation by opening the operation in the workflow designer. Changes here will be very similar to what was done for the person add operation.

Click on Search Relevant Data.

Add a rolelist relevant data item.

Add a customApprovalOperationName relevant data item with a default value of My Custom Role Approval. This name could be any global operation name that has been setup for being a custom role approval operation (shown later in this example).

The final extension activity after mapping all relevant data items. Click OK to save the activity and click OK to save the person modify operation.

Click on the Global operation level and click on Add....

Specify the Operation Name to be My Custom Role Approval (the name we specified earlier in the person add/modify customApprovalOperationName's default value).

After the workflow designer opens, click on the Properties button in the upper right.

Two input parameters are required in order to use this global operation as the custom approval operation name. These input parameters are personIn and roleIn and will need to be added.

personIn has the type of Person.

roleIn has the type of Organizational Role

Final input parameter list

Drag in a new APPROVAL activity put it between START and END while connecting transitions as shown.

Open the approval activity and specify the Participant as Role Owner. Map the input parameters roleIn and personIn.

On the Notification tab, add the following to the text and XHTML bodies:

This is a role owner approval for role: <JS>roleIn.get().name;</JS>

The notification can be customized further but for this example this is the only modification made.

On the Action Text tab, uncheck Use Notification Text as Action Text and specify the following as the action text:

This is a role owner approval for role: <JS>roleIn.get().name;</JS>

The action text can be customized further but for this example this is the only modification made.

On the Postscript tab, add the following javascript which will bubble up the result of the approval activity which is required. This result is used to remove or leave the given role on the person object before the person is stored in the data store.

process.setResult(activity.resultSummary, activity.resultDetail);

Click OK to save the approval activity and click OK to save the new global operation named My Custom Role Approval.

All changes are now complete. During any person add or modify, approval(s) will be generated for any new role(s) added to the given person using the My Custom Role Approval global operation. Approvals will be generated for each role of the new roles provided the role has an owner defined.

<script>
    roleOwnerExists.set("false");
    var per = person.get();
    var rolesArray = per.getNewRoles();
    for( var i=0; i<rolesArray.length;i++) {
        var owners = rolesArray[i].getProperty("owner");
        if(owners.length!=0){
            roleOwnerExists.set("true");
            break;
        }
    }

</script>

    roleOwnerExists.get()=="false";

    roleOwnerExists.get()=="true";

    var per = person.get();
      with the following line:
    var per = Entity.get();

    var rolesArray = per.getNewRoles();
      with
    var rolesArray = rolelist.get ();

Back up one level