User Task Assignment

This article looks user tasks in more detail. It explores different ways a task could be assigned when the users responsible for it aren't known.

Types of Assignment

There are three ways you can assign tasks to users.

Assignee

A task with an assignee will be assigned directly to that user. The assignee can only ever be a single user.

You can pick a user in your design:

or use the value of a process variable that holds a username:

Candidate Users and Groups

Candidates are lists of users who can claim tasks, generally using the Self Service or User Requests templates, or from the iCM homepage (if an iCM user has a site user alias). Users and groups are aggregated, so every listed user and every user in every group becomes a potential candidate.

Lists of users users and groups can be set in your design or taken from a process variable, in a similar way to the assignee. Each list should be an array of user names or group names (you can't combine user names and group names in the same list). For example:

Could pick up the value from a script task or End Point call that set:

execution.setVariable("users",["timg","timg2"]);

Finding Users

The workflow engine is aware of some users, like the user who started an instance or completed a task. You can also look up users using the iCM API worker.

Initiator

When a process instance starts the username of the user who started it is saved in a process variable. By convention the variable is called initiator. You can change the name of this variable in the workflow start event, but there's really no need to.

Preceding Task Users

When a task is completed, the username of the user who completed it is passed back to the workflow engine.

For example, this task has an ID of "confirmtask".

When a user completes it, this variable is automatically created in the workflow instance.

All tasks create variables named _taskid_completed - which is a good reason to enter human-readable IDs for your tasks rather than letting the process modeller assign random IDs to them. Similar variables are created when a task is claimed and released.

You can use this variable to assign future tasks back to this user, or in your script tasks. The assignee or candidate of a later task could be set as:

${_confirmtask_completed.user}

This way of assigning tasks is useful if you are also using Task Chaining.

Looking Up Users

The iCM API worker has various methods you can use to look up users. CSUserMultiple_get is the most useful in this situation as it can return the users in certain groups or whose names match a filter.

You can call the iCM API worker directly using the API Server task or you could use the End Point task to call an End Point which then calls the worker.

The Parameters

The parameters script task sets a variable called getUsers. Its value will be passed to the API Server.

execution.setVariable("getUsers", {
    "get": "UserName",
    "set": {
        "GroupList": 2
    }
});

The Task

The task properties set the worker to call, the method on the worker, the name of the variable that holds the parameters (set in the preceding script task) and the name of the variable that the result will be stored in.

Handling the Result

The result returned form the API Server is stored in a variable called APICALLRESULT. It looks like this:

{
    "multipleItemData": [{
        "UserName": "TIMG",
        "_ItemClass": "CSUser"
    }, {
        "UserName": "TIMG2",
        "_ItemClass": "CSUser"
    }],
    "itemData": {
        "_ItemClass": "CSUserMultiple"
    }
}

To turn that into something a user task can use, the second script task pushes the usernames into an array.

var userArr = [];
if (APICALLRESULT.multipleItemData) {
    for (var i = 0; i < APICALLRESULT.multipleItemData.length; i++) {
        var userName = APICALLRESULT.multipleItemData[i].UserName;
        userArr.push(userName);
    }
}
execution.setVariable("USERARRAY", userArr);

Which ends up as ["TIMG", "TIMG2"].