Workflow Functions for Work Items
This topic documents the available workflow Functions for configuring the workflow for Work Items. Whether or not a function runs may be configured to depend on satisfying one or more Work Item workflow Conditions. For procedural information, see Configure Work Item workflow.
AddDefaultApprovals
Adds default approvals for the Work Item. More specifically, it sets approval status to waiting for a specified list of users.
Parameters:
Comma-separated list of user IDs comprising the default list of approvers that are added to the Work Item when executing a workflow action.
Comma-separated list of role IDs comprising the default role(s) for approvers. All users with a specified role are added to the Work Item when executing a workflow action.
Required permission: Work Items: Permission to MODIFY
Changed Field
Changes the value of a specified field. Only setting of a date type field to current date, or a date-time type field to the current date-time is supported. The value type set depends on the type of the target field.
Parameters:
The ID of the field to be changed.
Only current.date is supported. It sets either a date or date-time value depending of the type of the target field specified in field.name.
ClearField
Clears existing value in the specified Work Item field.
Parameter:
ID of the field to clear. This field should not be a required field.
The ClearField function will not work with the plannedIn field because it is actually part of a Plan, not the Work Item.
CreateLinkedWorkItem
Creates a linked or backlinked Work Item using a specified type, link role, and a set of categories. The new Work Item is assigned according to the configured Auto-assignment scheme.
Parameters:
Required. The type of the new Work Item to be created. Value is the ID of a configured Work Item type.
Required. Link role of the link that will be created between the original and the new Work Item. Value is the ID of a configured link role.
Optional. If specified, the new Work Item is backlinked. Otherwise, it is linked.
Possibly required. Comma-separated list of IDs of the Categories to be applied to the new Work Item.
Whether or not this parameter is required depends on the general workflow configuration, which may or may not be set to require that Categories be specified when a new Work Item is created. The parameter is optional in the default global configuration.
LinkedWorkItemsStatusChange
Traverses incoming and outgoing links of having specified roles, finds all target Work Items, and checks if they are in one of the specified valid states. Any Work Items that are not in one of the valid states are transitioned to the target state, and optionally, some of their fields are cleared.
Parameters:
Comma-separated list of outgoing link roles to check.
Comma-separated list of incoming link roles to check.
Comma-separated list of valid statuses for found Work Items.
Status to which found Work Items will be transitioned.
Attributes that should be cleared for found Work Items.
MarkWorkflowSignaturesAsObsolete
Removes all of the Work Item signatures signed on the statuses that precede the one you've defined it for.
Parameters: none.
For example, one or more approvers signed a workflow status, but the item subsequently needs amendments that invalidate the signature(s). If this function is defined for, let's say the Reopen action, then all workflow signatures that Reviewed and Approved the item, are removed if the Work item is reopened. The removed signatures are still tracked in the Work Item's History.
ResetApprovalsState
Resets all approvals for the current Work Item to the waiting state.
Parameters: none.
Required permissions: APPROVE/DISAPPROVE as ANOTHER USER or RESET APPROVALS.
ScriptFunction
Invokes a custom script to perform some action or actions in conjunction with a workflow transition. For details, please see Scripted Workflow Functions and Conditions > ScriptFunction.
SetDate
Sets the specified field to the current date OR date-time, depending on the type of that field.
Parameter:
ID of the field have a date or date-time value set in it. The field specified must be of a type compatible with a date type OR a date-time type value.