JavaScript Filter

You can automatically assign tasks to subsets of teams with a User Task. By adding a filter to the team, you can assign the task to users who have a specific role on the team or who share some other criteria. JavaScript expressions let you customize the filter to meet your exact needs.

When creating your JavaScript filter there are few things to keep in mind:

• As you enter methods from the drop-down menu, they will be prefaced with the "team" object. This object is created before your script runs and references the team you've assigned the task to.
• If you want your filter to use multiple methods, for example to get users who didn't submit a form in the previous step and that have the Reviewer role, use one of the helper methods listed below to combine them.
• Your finished script must include an expression that sets the value of the $result variable (which is declared before your script runs). The value in the $result variable should be an array of team member objects, created by the methods in the drop-down menu and the helper methods listed below. Thus, you will want to set the value of the $result variable to the output from one of these methods. For example: $result = team.getAllMembers()
• When filtering by team, team administrators or managers that do not have member rights will not be included in the results.

Methods

Use the following methods to create your filter.

Parameters: Possible parameters are noted in italics. If an expression takes parameters, you can pass multiple parameters in a comma separated list and the expression will return team members who satisfy any of the parameters.

• findMembersByRole('RoleName'): Returns the team members (any members with the team member security role) who have at least one of the roles specified. If you click inside the parentheses, a list of available roles will appear for you to choose from.

Example: To return all the team members who have the Admin or Assistant Admin roles, use the following JavaScript snippet:

$result = team.findMembersByRole('Admin', 'Assistant Admin');

• excludeRoles('RoleName'); Returns the team members who do not have the specified roles. If you click inside the parentheses, a list of available roles will appear for you to choose from.
• findTaskLastSubmitters(StepID); Returns the team member who submitted a form the last time the specified step ran.

Tip: The step's ID number is passed in as the parameter. You can find the step's ID number at the top of the task's configuration pane. Show me where this is. Step IDs are unique in each process, and will not change even if the step is exported, imported, or copied.



• findTaskSubmitters(StepID); Returns the team members who submitted a form on the specified step. If the step ran multiple times in the process, this expression will return a list of all the team members who submitted a form in this step.
• excludeTaskLastSubmitters(StepID); Returns the team members who did not submit a form the last time the specified step ran.

Example: The user who approved the form in the last Approval step should not be able to approve the form in this user task as well. To return the team members who did not submit a form the last time the Approval step ran, use the following JavaScript snippet. In this example, the step's ID number is 5.

$result = team.excludeLastTaskSubmitters(5);

• excludeTaskSubmitters(StepID); Returns the team members who did not submit a form on the specified step. If the step ran multiple times in the process, this expression will return a list of all the team members who did not submit a form in this step.
• getAllMembers(); Returns all team members in the team. (This expression is not shown in the list of expressions when creating a filter.)
• findTeamMembersByUserName(Username); Finds one or more team members in the team using the username. To specify more than one team member, separate each team member with a comma. You can use this method to assign a task to only team members with the specified username.

Example: If explicitly listing a specific user in the filter with an Active Directory account, replace the single backslash ("\") with a double backslash ("\\").

$result = team.findTeamMembersByUserName('domain\\userName');

• findTeamMembersByDisplayName(DisplayName); Finds one or more team members in the team using the display name. To specify more than one team member, separate each team memebr with a comma. You can use this method to assign a task to only the team members with the specified display name.

Note: When you test JavaScript that uses TaskSubmitter methods, it will assume the previous task has not run. Thus, during the test, no team members will be returned for findTaskSubmitters and all team members will be returned for excludeTaskSubmitters.

Helper methods

To use more than one of the expressions listed above in a single filter, you will need to assign each expression to a variable and then pass those variables to a helper method. Alternatively, you can directly pass the expressions as helper method parameters.

Parameters: The union and intersection helper methods can take any number of parameters. The difference method requires two parameters.

• $util.union Returns the team members that are in either of the lists passed as parameters.

Example: To return all the team members that are either Admins or Analysts, use one of the following JavaScript snippets:

var admins = team.findMembersByRole('Admin');
var analysts = team.findMembersByRole('Analyst');
$result = $util.union(admins, analysts);

OR

$result = $util.union(team.findMembersByRole('Admin'), team.findMembersByRole('Analyst'));

• $util.intersection Returns the team members that are in both of the lists passed as parameters.

Example: To return all the team members that have both the Specialist and Reviewer roles, use one of the following JavaScript snippets:

var specialists = team.findMembersByRole('Specialist');
var reviewers = team.findMembersByRole('Reviewer');
$result = $util.intersection(specialists, reviewers);

OR

$result = $util.intersection(team.findMembersByRole('Specialist'), team.findMembersByRole('Reviewer'));

• $util.difference Returns the team members that are in the list that is passed as the first parameter but not in the list passed as the second parameter.

Example: To return all the analysts who do not have the Accountant role.

var analysts = team.findMembersByRole('Analyst');
var accountants = team.findMembersByRole('Accountant');
$result = $util.difference(analysts, accountants);

OR

$result = $util.difference(team.findMembersByRole('Analyst'), team.findMembersByRole('Accountant'));

You can combine helper methods to create even more nuanced filters.

Example: To return all the administrators, and return all team members that have both the Specialist and Reviewer roles, use one of the following JavaScript snippets:

var specialists = team.findMembersByRole('Specialist');
var reviewers = team.findMembersByRole('Reviewer'); 
var bothRoles = $util.intersection(specialists, reviewers); 
var admins = team.findMembersByRole('Admin'); 
$result = $util.union(bothRoles, admins);

OR

$result = $util.union($util.intersection(team.findMembersByRole('Specialist'), team.findMembersByRole('Reviewer')), 
team.findMembersByRole('Admin'));

Advanced example

You can combine these JavaScript expressions and helper methods with additional JavaScript functions to account for more complex situations.

Example: You want to assign a task back to the people who were assigned the task the last time. If no one was assigned to the task previously, then you want to assign the task to the team. You can use the following JavaScript, replacing "6" with the step's ID number.

var assignedTo;
assignedTo=team.findTaskLastSubmitters(6);
if (Object.keys(assignedTo).length == 0)
	$result=team.getAllMembers();
else
	$result=assignedTo;

Using $test in the team filter

You can use the keyword “$test” in a team filter to view the attributes of the results found. Those results are displayed in a separate “$test Output” field. For example, using “$test” instead of “$result” in the first statement of the following, you can see each resulting user as an object with a set of attributes:

$test=team.excludeRoles('roledoesntexist')
$result=team.excludeRoles('roledoesntexist')

For example, if “=team.excludeRoles('roledoesntexist')” returns two team members, you can prepend “$test” to see the attributes of each user, like the user’s roles and user name. The following returns the results along with a second “$test Output” field for viewing each object and the attributes: