WorkitemFinder Extension

The WorkitemFinder Extension is a permanent extension started at FNZ Studio startup. The extension runs on top of the in-memory filtering in FNZ Studio (Core) Platform and provides the following functionality:

  • A connection between the front end UI and the existing back end functionality.
  • Out-of-the-box filters to retrieve specific subsets of Workitems (based on status, ownership, attributes and more).
  • Sorting, paging, and text-based searching capabilities on the Workitems. The querying functionalities are exposed through the Process:FindWorkitems function which can be used by FNZ Studio to retrieve the Workitem data.
An image describing the composition of the WorkitemFinder extension.

Examples:

  1. When used in a Screen, the user selection regarding search, sorting, and filters is passed to the Process:FindWorkitems function, which retrieves the requested data from the distributed in-memory backend. The function then searches, sorts, and pages the data and returns it to the Screen.
  2. When used in a Process, the Process:FindWorkitems function uses predefined filters to retrieve the requested data from the distributed in-memory backend when the Process is triggered. The function sorts and pages the data and passes it to the next step of the Process where further actions can be performed on this filtered group of Workitems.

Process:FindWorkitems Function

The Process:FindWorkitems function is used by FNZ Studio to retrieve the Workitem data matching the specified criteria. The function relies on four input parameters:

  • $filterStructure - A WorkitemBaseFilter, i.e. a structure that defines the filtering to be applied to all available Workitems.
  • $searchCriteria - A WorkitemFinderSearchCriteria that defines the criteria to be used for additional filtering of the Workitems based on a value contained inside the specified Workitems properties. It is optional.
  • $sortCriteria - A WorkitemFinderSortCriteria that defines the sorting criterion to be used for sorting the filtered Workitems. If not provided, the Workitem list is sorted by descending creation date.
  • $pageCriteria - A WorkitemFinderPageCriteria that defines the page size and page number which is returned. If not provided, the default page size and page number are set to 10 and 1 respectively. The maximum page size accepted is 2147483647 (Integer.MAX_VALUE): you can use this value to retrieve all the results at once.

The return value of the function is the Primitive Type WorkitemFinderResult, which exposes the following methods:

  • getOverallNumberOfItems() - Returns the total number of Workitems matching the given filter and search criteria.
  • getNumberOfPages() - Returns the total number of pages defined by the provided page criterion.
  • getWorkitems() - Returns an Indexed Workitem that contains all the Workitems matching the given filter and search criteria falling in the page number provided in the page criterion (or page 1 if a null WorkitemFinderPageCriteria was provided) with the given sorting.
  • getErrors() - Whenever an exception is encountered during the filtering process, it is collected and reported in a Named String. In this map, a key is the ID of a Workitem whose filtering returned one or more errors, while the value indicates all of the collected errors divided by a pipe (|).

WorkitemFinderField

A WorkitemFinderField is a Primitive Type used to define which field of a Workitem has to be analyzed to process the existing Workitems. It has four properties:

  • source - The name of the source that owns the property. Valid sources are:
    • instance - The Workflow Instance that owns the Workitem.
    • workitem - The Workitem.
    • user - The user assigned to the Workitem.
    • instanceAttribute - A custom attribute of the Workflow Instance.
    • tokenAttribute - A custom attribute of the Workflow Token underlying the Workitem.
  • name - The name of the examined attribute.
  • type - A String representing the type of the attribute. Valid values are String, Number, and Date.
  • useInheritedAttributeValue - A Boolean flag. Set it to true to inherit the token attributes from the parent when the source is set to tokenAttribute.

The allowed values for the above properties are listed in the following table:

source name type
instance id Number
instance processId String
instance status String
instance creationTime Date
instance modificationTime Date
workitem id Number
workitem userId String
workitem status String
workitem creationTime Date
workitem modificationTime Date
workitem swimlaneName String
workitem swimlaneDescription String
workitem swimlaneTaskListName String
workitem elementDescription String
workitem elementName String
workitem elementTaskListName String
workitem phaseName String
workitem phaseTaskListName String
workitem phaseDescription String
workitem priority Number
workitem dueDate Date
user first name String
user last name String
instanceAttribute * String/Date/Number
tokenAttribute * String/Date/Number
Note: The * in the 'name' column for the types instanceAttribute and tokenAttribute stands for a custom attribute name.

An instance of WorkitemFinderField can be created by using another Primitive Type, the WorkitemFinderFieldFactory, that allows exploiting all the benefits of auto-completion in the script editor. Some examples:

Copy 


WorkitemFinderFieldFactory.createInstanceField().withId();


WorkitemFinderFieldFactory.createWorkitemField().withDueDate();


WorkitemFinderFieldFactory.createUserField().withFirstName();


WorkitemFinderFieldFactory.createInstanceAttributeField().withStringField('aCustomPropertyName');


WorkitemFinderFieldFactory.createInstanceAttributeField().withNumberField('aCustomPropertyName');


WorkitemFinderFieldFactory.createInstanceAttributeField().withDateField('aCustomPropertyName');


WorkitemFinderFieldFactory.createTokenAttributeField().withStringField('aCustomPropertyName');


WorkitemFinderFieldFactory.createTokenAttributeField().withNumberField('aCustomPropertyName');


WorkitemFinderFieldFactory.createTokenAttributeField().withDateField('aCustomPropertyName');


WorkitemFinderFieldFactory.createInheritedTokenAttributeField().withStringField('aCustomPropertyName'); 


WorkitemFinderFieldFactory.createInheritedTokenAttributeField().withNumberField('aCustomPropertyName'); 


WorkitemFinderFieldFactory.createInheritedTokenAttributeField().withDateField('aCustomPropertyName'); 


The three fields source, name, and type are all accessible via the getter methods getSource(), getName(), and getType().

Filters

The WorkitemFinder extension offers four types of filters:

  • Basic - All the fundamental filters (e.g. logical operators and Workitem property filters)
  • Current Assignee - All the filters used to check if the current user, one of the roles/groups the user is assigned to, or a member of these roles/groups is currently assigned to a Workitem.
  • Participant - All the filters to check if the current user, one of the roles/groups the user is assigned to, or a member of these roles/groups was assigned to a Workitem, but are not currently assigned.
  • FNZ-specific - Filters working with concepts used by other FNZ products, for example Hierarchy Ids from FNZ OneX.

Each filter is of the type WorkitemBaseFilter. Moreover, each filter is defined as a Primitive Type.

Basic Filters

The following filters are included in the Basic category:

  • WorkitemAndFilter - Defines a chain of filters which is logically evaluated with AND. Add filters with the addFilter() method. Check if at least one filter has been added with the isEmpty() method. E.g.:

    Copy 
        WorkitemAndFilter $andFilter := new WorkitemAndFilter;
        $andFilter.addFilter($filter1);
        $andFilter.addFilter($filter2);

    A Workitem is kept if all the filters in the AND chain match the defined conditions.

    Performance tip: The filters in the chain are evaluated in sequence and the evaluation of the chain is interrupted as soon as a filter does not accept the evaluated token (which means that the overall condition is false). Therefore, the order of adding the filters can speed up the expression.

  • WorkitemOrFilter - Defines a chain of filters to be logically evaluated with OR. Add filters with the addFilter() method. Check if at least one filter has been added with the isEmpty() method. E.g.:

    Copy 
        WorkitemOrFilter $orFilter := new WorkitemOrFilter;
        $orFilter.addFilter($filter1);
        $orFilter.addFilter($filter2);

    A Workitem is kept if one of the filters in the OR chain matches the defined conditions.

    Performance tip: The filters in the chain are evaluated in sequence and the evaluation of the chain is interrupted as soon as a filter accepts the evaluated token (which means that the overall condition is true). Therefore, the order of adding the filters can speed up the expression.

  • WorkitemNotFilter - Defines a filter that negates the one added with the addFilter() method. Check if a filter to be negated has been added with the isEmpty() method. E.g.:

    Copy 
        WorkitemNotFilter $notFilter := new WorkitemNotFilter;
       $notFilter.addFilter($anotherFilter);

    A Workitem is kept if the filter in the chain matches the negated conditions.

  • WorkitemBusinessObjectPrefixFilter - Keeps all the Workitems whose Workflow ID starts with the given prefix. E.g.:

    Copy 
        String $boPrefix := 'Prefix';
        WorkitemBusinessObjectPrefixFilter $filter := WorkitemBusinessObjectPrefix.newInstance($boPrefix);

  • WorkitemCustomFilter - Evaluates the given expression. E.g.:

    Copy 
        WorkitemCustomFilter $filter := new WorkitemCustomFilter;
       $filter.setExpression($item.getStatus() == 'Active');

    where $item is the default variable that matches the WorkflowToken. A custom variable of the type WorkflowToken has to be provided via the setter method setVariable(). If the provided variable is not of the type WorkflowToken, then an exception is thrown. E.g.

    Copy 
        WorkflowToken $tk;
        WorkitemCustomFilter $filter := new WorkitemCustomFilter;
       $filter.setExpression($tk.getStatus() == 'Active');
       $filter.setVariable($tk);

    The expression must be provided as an argument of the setExpression method. Moreover, the expression cannot rely on variables other than the $item variable (or the custom one provided in the setVariable() method).

    Performance note: Due to the evaluation of a custom expression, the load resulting from the execution of this filter is not negligible and the filter should not be overused. For this reason, when added into the chain for a WorkitemAndFilter or a WorkitemOrFilter, this filter is automatically added at the end of the chain.Contact Solution Engineers to assess the actual need for using this filter.

  • WorkitemFilterByInstanceAttribute - Keeps a Workitem if the Workflow Instance has an attribute matching one or more of the given values. The filter can be created using the static method newInstance:

    Copy 
        Any $value;
        WorkitemFilterByInstanceAttribute $filter := WorkitemFilterByInstanceAttribute.newInstance('attributeName', $value);

    Alternatively, the filter can be created with a list of accepted values for matching the attribute:

    Copy 
        Indexed Any $values;
        WorkitemFilterByInstanceAttribute $filter := WorkitemFilterByInstanceAttribute.newInstance('attributeName', $values);

  • WorkitemFilterByInstanceAttributeContains - Keeps a Workitem if the Workflow Instance has an attribute of the type String whose value contains one or more of the given String values. The filter can be created using the static method newInstance and has an option to ignore the case:

    Copy 
        Boolean $ignoreCase := true;
        WorkitemFilterByInstanceAttributeContains $filter := WorkitemFilterByInstanceAttributeContains.newInstance('attributeName', 'value', $ignoreCase);

    Alternatively, the filter can be created with a list of accepted values for matching the attribute: {code:[language:appwayscript,numbering:false]}
    Boolean $ignoreCase := false; Indexed String $values := ['Value', 'Value']:String; WorkitemFilterByInstanceAttributeContains $filter := WorkitemFilterByInstanceAttributeContains.newInstance('attributeName', $values, $ignoreCase);

  • WorkitemFilterByInstanceAttributePreprocess - Evaluates the given expression related to a Workflow Instance attribute and verifies if the processed expression is equal to the given value. The expression can access the token and the attribute using the default variables $item and $attribute, respectively. The default variables can be overridden using the setAttributeVariable and setWorkflowTokenVariable methods. If the provided variable for the token is not of the type WorkflowToken, then an exception is thrown. E.g.:

    Copy 
        WorkflowToken $token;
        String $pastState;
        WorkitemFilterByInstanceAttributePreprocess $filter := WorkitemFilterByInstanceAttributePreprocess.newInstance('attributeName', 'attributeValue');
        $filter.setExpression(TRIM(UPPERCASE($pastState)) & TRIM(LOWERCASE($token.getStatus())));
        $filter.setAttributeVariable($pastState);
        $filter.setWorkflowTokenVariable($token);

    The expression must be provided as an argument of the setExpression method. Moreover, the expression cannot rely on variables other than the $item and $attribute variables (or the custom ones provided in the setVariable()and setAttributeVariable() methods).

    Performance note: Due to the evaluation of a custom expression, the load resulting from the execution of this filter is not negligible and the filter should not be overused. For this reason, when added into the chain for a WorkitemAndFilter or a WorkitemOrFilter, this filter is automatically added at the end of the chain.Contact Solution Engineers to assess the actual need for using this filter.

  • WorkitemFilterByInstanceAttributePreprocessContains - Evaluates the given expression related to a Workflow Instance attribute and verifies if the processed expression contains the given value. The case cannot be ignored. The expression can access the token and the attribute using the default variables $item and $attribute, respectively. The default variables can be overridden using the setAttributeVariable and setWorkflowTokenVariable methods. If the variable provided for the token is not of the type WorkflowToken, then an exception is thrown. The use is similar to WorkitemFilterByInstanceAttributePreprocess (see just above).

    Performance note: Due to evaluation of a custom expression, the load resulting from the execution of this filter is not negligible and the filter should not be overused. For this reason, when added into the chain for a WorkitemAndFilter or a WorkitemOrFilter, this filter is automatically added at the end of the chain.Contact Solution Engineers to assess the actual need for using this filter.

  • WorkitemFilterByStatus - Keeps a Workitem only if the status matches the given values. E.g.

    Copy 
       String $statusCode := 'Active';
        WorkitemFilterByStatus $filter := WorkitemFilterByStatus.newInstance($statusCode);

  • WorkitemFilterByTokenAttribute - Keeps a Workitem if the token has an attribute matching one or more of the given values. The filter can be created using the static method newInstance:

    Copy 
        Any $value;
        WorkitemFilterByTokenAttribute $filter := WorkitemFilterByTokenAttribute.newInstance('attributeName', $value);

    Alternatively, the filter can be created with a list of accepted values for matching the attribute:

    Copy 
        Indexed Any $values;
        WorkitemFilterByTokenAttribute $filter := WorkitemFilterByTokenAttribute.newInstance('attributeName', $values);

  • WorkitemFilterByTokenAttributeContains - Keeps a Workitem if the token has an attribute of the type String whose value contains one or more of the given String values. The filter can be created using the static method newInstance and has an option to ignore the case:

    Copy 

        Boolean $ignoreCase := true;

        WorkitemFilterByTokenAttributeContains $filter := WorkitemFilterByTokenAttributeContains.newInstance('attributeName', 'value', $ignoreCase);

    Alternatively, the filter can be created with a list of accepted values for matching the attribute:

    Copy 
        Boolean $ignoreCase := false;
        Indexed String $values := ['Value', 'vAlUe']:String;
        WorkitemFilterByTokenAttributeContains $filter := WorkitemFilterByTokenAttributeContains.newInstance('attributeName', $values, $ignoreCase);

  • WorkitemFilterByTokenAttributePreproces - Evaluates the given expression related to a token attribute and verifies if the processed expression is equal to the given value. The expression can access the token and the attribute using the default variables $item and $attribute, respectively. The default variables can be overridden using the setAttributeVariable and setWorkflowTokenVariable methods. If the provided variable for the token is not of the type WorkflowToken, then an exception is thrown. The use is similar to WorkitemFilterByInstanceAttributePreprocess (see above).

    Performance note: Due to the evaluation of a custom expression, the load resulting from the execution of this filter is not negligible and the filter should not be overused. For this reason, when added into the chain for a WorkitemAndFilter or a WorkitemOrFilter, this filter is automatically added at the end of the chain.Contact Solution Engineers to assess the actual need for using this filter.

  • WorkitemFilterByTokenAttributePreprocessContains - Evaluates the given expression related to a token attribute and verifies if the processed expression contains the given value. The expression can access the token and the attribute using the default variables $item and $attribute, respectively. The default variables can be overridden using the setAttributeVariable and setWorkflowTokenVariable methods. If the provided variable for the token is not of the type WorkflowToken, then an exception is thrown. The use is similar to WorkitemFilterByInstanceAttributePreprocess (see above).

    Performance note: Due to the evaluation of a custom expression, the load resulting from the execution of this filter is not negligible and the filter should not be overused. For this reason, when added into the chain for a WorkitemAndFilter or a WorkitemOrFilter, this filter is automatically added at the end of the chain.Contact Solution Engineers to assess the actual need for using this filter.

  • WorkitemFilterByUser - Accepts a Workitem only if the user ID from the inherited queue name value of the token matches one of the given IDs. E.g.

    Copy 
       WorkitemFilterByUser $filter := WorkitemFilterByUser.newInstance('userid');

    where the newInstance method also accepts a list of user IDs.

  • WorkitemFilterByUserAttribute - Keeps a Workitem if the user ID from the inherited queue name value of the token has an attribute preference equal to the given value. E.g.

    Copy 
        WorkitemFilterByUserAttribute $filter := WorkitemFilterByUserAttribute.newInstance('preferenceAttribute', 'value');

  • WorkitemFilterByUserAttributeContains - Keeps a Workitem if the user ID from the inherited queue name value of the token has an attribute preference that contains the given value, e.g.:

    Copy 
        WorkitemFilterByUserAttributeContains $filter := WorkitemFilterByUserAttributeContains.newInstance('preferenceAttribute', 'value');

  • WorkitemNonHiddenFilter - Accepts a Workitem only if the element in the process diagram on which the corresponding token is located is not set as hidden. The hidden property is checked recursively.

  • WorkitemReadyOrActiveFilter - Keeps a Workitem only if the status is Ready or Active.

  • WorkitemScreenTaskFilter - Keeps a Workitem if the token is currently on an ExternalTask (i.e. DataTask, ManualTask, PlaceholderTask, RedirectTask, ScreenTask).

  • WorkitemRangeFilter - Keeps a Workitem if the property specified by an WorkitemFinderField of the type Date or Number falls in the specified range. For convenience, it can be created by resorting to a builder Primitive Type, i.e. the WorkitemRangeFilterFactory:

    Copy 
        WorkitemRangeFilterFactory.createInstanceRangeFilter().withCreationTimeBetween($dateFrom, $dateTo)

    Alternatively, it can be created with a custom attribute name:

    Copy 
        WorkitemRangeFilterFactory.createTokenAttributeRangeFilter().withNumberFieldBetween('attributeName', $numberFrom, $numberTo)

    Only the WorkitemFinderFields listed in the following table can be used with the range filter:

source name type
instance creationTime Date
instance modificationTime Date
workitem creationTime Date
workitem modificationTime Date
workitem priority Number
workitem dueDate Date
instanceAttribute * Date/Number
tokenAttribute * Date/Number

The token attribute range filter can also be created with the option of filtering values inherited by parent tokens. This can be done using either the WorkitemFinderField created with the inherited attribute value option or by using the builder as follows:

Copy 
WorkitemRangeFilterFactory.createInheritedTokenAttributeRangeFilter().withNumberFieldBetween('attributeName', $numberFrom, $numberTo)
Important! The following filters should not be used when the same logic can be achieved by combining other filters:
  • WorkitemCustomFilter
  • WorkitemFilterByInstanceAttributePreprocess
  • WorkitemFilterByInstanceAttributePreprocessContains
  • WorkitemFilterByTokenAttributePreprocess
  • WorkitemFilterByTokenAttributePreprocessContains
nThe reason is a potential performance impact which can occur when executing custom expressions.

Current Assignee Filters

The following filters are included in the Current Assignee category:

  • WorkitemMyTasksFilter - Keeps a Workitem for which the current user is the assignee. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyTasksFilter();

  • WorkitemMyGroupsFilter - Keeps a Workitem which is assigned to any of the groups that the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyGroupsFilter();

  • WorkitemMemberOfMyGroupsFilter - Keeps a Workitem for which any user in the same groups as the current user is the assignee. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMemberOfMyGroupsFilter();

  • WorkitemMyGroupsOrMemberOfMyGroupsFilter - Keeps a Workitem if:

    • the Workitem is assigned to any of the groups the current user is a member of, or
    • any user in the same groups as the current user is the assignee

    Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyGroupsOrMemberOfMyGroupsFilter();

  • WorkitemMyRolesFilter - Keeps a Workitem which is assigned to any of the roles that the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyRolesFilter();

  • WorkitemMemberOfMyRolesFilter - Keeps a Workitem for which any user in the same roles as the current user is the assignee. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMemberOfMyRolesFilter();

  • WorkitemMyRolesOrMemberOfMyRolesFilter - Keeps a Workitem if:

    • the Workitem is assigned to any of the roles that the current user is a member of, or
    • any user in the same roles as the current user is the assignee

    Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyRolesOrMemberOfMyRolesFilter();

  • WorkitemMyGroupsOrMyRolesFilter - Keeps a Workitem which is assigned to any groups or roles the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemCurrentAssigneeFilterBuilder:

    Copy 
        WorkitemCurrentAssigneeFilterBuilder.createWorkitemMyGroupsOrMyRolesFilter();

Participant Filters

This set of filters verifies groups, roles, or users set as participants of a given Workitem.

Each of the filters in this category looks for the content of the Workitem attribute provided by the participants.attribute config key or for the attribute name Participants if no config key is provided. The attribute is populated by the participant listener only if it is enabled (i.e. the participants.tracking.enabled configuration property is set to true) or if the attribute is populated using a script inside the Process to follow a custom logic. Otherwise, these filters always return false.

Be aware that, if the Workitem is assigned to the current user, it will not be accepted by any of the -participant' filters.

The following filters are included in the Participant category:

  • WorkitemIWasParticipantFilter - Keeps a Workitem that had as a participant: the current user. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemIWasParticipantFilter();

  • WorkitemMemberOfMyGroupsWereParticipantsFilter - Keeps a Workitem that had as a participant: any user in the same group as the current user. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMemberOfMyGroupsWereParticipantsFilter();

  • WorkitemMemberOfMyRolesWereParticipantsFilter - Keeps a Workitem that had as a participant: any user with any of the same roles as the current user. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMemberOfMyRolesWereParticipantsFilter();

  • WorkitemMyGroupsOrMemberOfMyGroupsWereParticipantsFilter - Keeps a Workitem that had as a participant: any user in the same groups as the current user or any of the groups the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMyGroupsOrMemberOfMyGroupsWereParticipantsFilter();

  • WorkitemMyGroupsOrMyRolesWereParticipantsFilter - Keeps a Workitem that had as a participant: any group that the current user is a member of or any role that the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMyGroupsOrMyRolesWereParticipantsFilter();

  • WorkitemMyGroupsWereParticipantsFilter - Keeps a Workitem that had as a participant: any of the groups that the current user is a member of. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMyGroupsWereParticipantsFilter();

  • WorkitemMyRolesOrMemberOfMyRolesWereParticipantsFilter - Keeps a Workitem that had as a participant: any user with any of the same roles as the current user or any of the roles assigned to the current user. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMyRolesOrMemberOfMyRolesWereParticipantsFilter();

  • WorkitemMyRolesWereParticipantsFilter - Keeps a Workitem that had as a participant: any of the roles assigned to the current user. Instantiation can be performed by using the new operator or via the Primitive Type WorkitemParticipantFilterBuilder:

    Copy 
        WorkitemParticipantFilterBuilder.createWorkitemMyRolesWereParticipantsFilter();
    In order to show the Workitems related to Data Tasks, the 'case.tasks.filtering.enabled' has to be set to false (the default value is true). Please, consider that this configuration property also applies to 'Current Assignee' filters.

FNZ-specific Filters

  • WorkitemFilterByFnzHierarchyIds - Keeps a Workitem if the process instance has an attribute with a pipe-separated list of values (for example: "001-2199321-A|002-9388121-X") and ALL these values are contained in the given list of FNZ Hierarchy Ids. The filter can be created using the static method newInstance which expects two arguments, an attribute name and the list of FNZ Hierarchy Ids:

    Copy 

        String $attributeName := "FNZ_HIERARCHY_IDS";

        Indexed String $fnzHierarchyIds := ["001-2199321-A", "002-9388121-X"]:String;

        WorkitemFilterByFnzHierarchyIds $filter := WorkitemFilterByFnzHierarchyIds.newInstance($attributeName, $fnzHierarchyIds);

    Note: This filter is available since WorkitemFinder extension version 9.1.0.

Process:IsEmptyLogicalWorkitemFilter Function

The Process:IsEmptyLogicalWorkitemFilter function is used to check if a given logical filter (an instance of either WorkitemAndFilter, WorkitemOrFilter, or WorkitemNotFilter) is empty (i.e. no filter has been added in to execute the Boolean logic). The function relies on one input parameter:

  • $filter - The WorkitemBaseFilter which is checked to see if it is empty.

The return value of the function is a Primitive Type Boolean, which is true when the filter is empty; false otherwise.

The function throws an exception if the given filter is null or is not one of the three filters listed above.

WorkitemFinderPageCriteria

WorkitemFinderPageCriteria is a Primitive Type used to specify the criteria to be used to create a page of Workitems which is returned. It has two fields, pageNumber and pageSize, both of the type Integer. Within the Studio, the type can be created using a fluent interface as follows:

Copy 
WorkitemFinderPageCriteria.newInstance().setPageNumber(1).setPageSize(5)

By default, pageNumber is 1 and pageSize is 10. Any value equal or lower than zero throws an exception.

The pageNumber value is obtained via the getter method getPageNumber(), while the pageSize value is obtained via the getter method getPageSize().

WorkitemFinderSearchCriteria

WorkitemFinderSearchCriteria is a Primitive Type used to specify the criteria to be used for keeping the Workitems that match a given search text. The search text must be contained in at least one of the WorkitemFinderFields provided to the WorkitemFinderSearchCriteria. The 'contains' check is case-insensitive.

For this purpose, the Primitive Type has two fields, searchText (type is String) and fields (type is Indexed WorkitemFinderField). The type can be created using a fluent interface as in the following example:

Copy 
WorkitemFinderField $field1 := WorkitemFinderFieldFactory.createInstanceField().withProcessId();
WorkitemFinderField $field2 := WorkitemFinderFieldFactory.createInstanceField().withStatus();
Indexed WorkitemFinderField $searchFields := NewIndexed(WorkitemFinderField);
$searchFields.addElement($field1);
$searchFields.addElement($field2);
WorkitemFinderSearchCriteria.newInstance().setSearchText('my text').setFields($searchFields);

The searchText field is obtained via the getter method getSearchText(), while the fields field is obtained via the getter method getFields().

Only the WorkitemFinderFields listed in the following table can be used for searching purposes:

source name type
instance id Number
instance processId String
instance status String
workitem id Number
workitem userId String
workitem status String
workitem swimlaneName String
workitem swimlaneDescription String
workitem swimlaneTaskListName String
workitem elementDescription String
workitem elementName String
workitem elementTaskListName String
workitem phaseName String
workitem phaseTaskListName String
workitem phaseDescription String
user first name String
user last name String
instanceAttribute * String/Number
tokenAttribute * String/Number

WorkitemFinderSortCriteria

WorkitemFinderSortCriteria is a Primitive Type used to specify the criterion to be used for sorting in the script function Process:FindWorkitems. Specifically, it sorts the Indexed Workitem defined after applying the filter structure and the optional search criteria to all of the available Workitems.

The WorkitemFinderSortCriteria Primitive Type has two fields, direction (type is String) and field (type is Indexed WorkitemFinderField). The Primitive Type can be instantiated using a fluent interface as follows:

Copy 
WorkitemFinderField $sortField := WorkitemFinderFieldFactory.createInstanceField().withProcessId();
WorkitemFinderSortCriteria.newInstance().setAscending().setField($sortField);
//Or to make it descending
WorkitemFinderSortCriteria.newInstance().setDescending().setField($sortField);

All WorkitemFinderFields can be used for sorting.

Note: The direction is obtained via the getter method getDirection() that returns "ascending" or "descending" (default).

The sort field is obtained via the getter method getField();.

Be aware that the Primitive Type uses default values when created. Specifically, WorkitemFinderSortCriteria.newInstance(); is equivalent to:

Copy 
WorkitemFinderField $workitemCreationTimeField := WorkitemFinderFieldFactory.createWorkitemField().withCreationTime();
WorkitemFinderSortCriteria.newInstance().setDescending().setField($workitemCreationTimeField);

WorkflowTokenStatusUtils

WorkflowTokenStatusUtils is a Primitive Type which offers the following methods allowing you to check Processes for Tokens with the specified status code:

  • getActiveStatusCode()
  • getCancelledStatusCode()
  • getCompletedStatusCode()
  • getNoneStatusCode()
  • getOutgoingStatusCode()
  • getReadyStatusCode()
  • getSuspendedStatusCode()

WorkitemFinder Participant Listener

The WorkitemFinder extension can be configured to keep track of the participants of a Workflow Token using a Process listener. This behavior can be enabled/disabled using the following configuration property available for the WorkitemFinder extension: participants.tracking.enabled (true by default).

Whenever a token is assigned, the participants of the token are obtained from the Workflow Instance attribute "Participants" (note that the attribute name can be overridden by defining a new name via the extension config key participants.attribute). The current participant is then appended to the previous participants. The pattern used to store the participants of a Workflow Token is:

Copy 
|{participant1}|{participant2}|

where {participant} is the placeholder for the participant ID.

Note: To stop tracking the participants of a token, set the token attribute doNotTrackParticipants into the token, e.g.: ProcessTokenSetAttribute(ProcessToken().getId(), 'doNotTrackParticipants', ''); Setting the value of the attribute to false will not enable participant tracking. Instead, use the ProcessTokenRemoveAttribute function.

WorkitemFinder Extension Indexing

Process Instance Indexing is a feature which allows defining indexes to speed up the filtering of Process Instances and Workflow Tokens.

The WorkitemFinder extension can use indexing to boost filtering when executing the Process:FindWorkitems function. Indexing is not enabled by default in the WorkitemFinder Extension. Please refer to the 'Enabling/Disabling Indexing' section below to learn how to enable/disable indexing in the WorkitemFinder extension. Moreover, indexing becomes effective only when indexes are defined for the filters being used in the Process:FindWorkitems function.

Enabling/Disabling Indexing

To enable/disable indexing in the WorkitemFinder Extension:

  1. In Studio, go to System Configuration > Extensions > Permanent Extensions section, right-click on the WorkitemFinder Extension, and then click on the Edit Configuration option.
  2. In the popup displayed, edit the indexing.enabled configuration property: Set the value to true to enable indexing (default), and to false to disable indexing.

Indexable Filters

The WorkitemFinder extension supports indexing for a subset of the available filters. If a filter supports indexing, an index can be created (refer to the documentation for indexing) using the Script Language. The following list reports the list of filters that support indexing. A sample script to be run for creating an index for these filters is also provided.

  • WorkitemFilterByUser - Enabled by default at the startup of the extension is indexing is enabled or when indexing get enabled. No further action required.

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_ReadyOrActiveStatusFilter_Index', 'ProcessTokenMember', 'status');

  • WorkitemReadyOrActiveFilter:

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_ReadyOrActiveStatusFilter_Index', 'ProcessTokenMember', 'status');

  • WorkitemFilterByStatus - If the status to be filtered is known in advance:

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_ActiveStatusFilter_Index', 'ProcessTokenMember', 'status=Active');

    Otherwise:

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_StatusFilter_Index', 'ProcessTokenMember', 'status');

  • WorkitemFilterByInstanceAttribute - String $attribute;// This must be initiated with the instance attribute name:

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_InstanceAttributeFilter_' & $attribute, 'ProcessInstanceAttribute', $attribute);

  • WorkitemFilterByTokenAttribute - String $attribute;// This must be initiated with the token attribute name:

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_TokenAttributeFilter_' & $attribute, 'ProcessTokenAttribute', $attribute);

  • WorkitemIWasParticipantFilterWorkitemMemberOfMyGroupsWereParticipantsFilterWorkitemMemberOfMyRolesWereParticipantsFilterWorkitemMyGroupsOrMemberOfMyGroupsWereParticipantsFilterWorkitemMyGroupsOrMyRolesWereParticipantsFilterWorkitemMyRolesOrMemberOfMyRolesWereParticipantsFilterWorkitemMyRolesWereParticipantsFilter For all of these filters you can run these scripts for creating indexes:

    Copy 

        String $attributeName := CONTEXT().getAdapterService().getAdapter('WorkitemFinder').getParticipantsAttributeName();

    Copy 

       CreateProcessInstanceIndex('WorkitemFinder_ParticipantsFilter_Index', 'ProcessTokenAttribute', $attributeName);

    Copy 

        CreateProcessInstanceIndex('WorkitemFinder_ParticipantsFilter_Index', 'ProcessInstanceAttribute', $attributeName);

As reported in the preceding list, indexing on the queue name is provided by default since filtering by task assignee is a common use case.

Note: The index name (e.g. 'WorkitemFinder_ReadyOrActiveStatusFilter_Index') is arbitrary.

Performance Tips

There is no standard for defining which indexes should be defined to optimize runtime. Optimizing the WorkitemFinder extension through indexing requires some effort in tuning indexes.

To this aim, a reliable tool that can help determine which indexes should be defined is the Function Statistics tab. This tab reports statistics related to the time required to execute the Script Functions. Go to Solution Maintenance > Script Language and filter the function names by Name: Process:FindWorkitems.

We recommend monitoring the Average Time column and reaching at least 1000-2000 invocations before deciding on a specific configuration.

Note that statistics must be reset after each change in the indexing configuration (e.g., enabling/disabling indexing, creating an index), otherwise numerical results could be misleading. Also, a transient period of 500 invocations should be considered after a configuration change.

For the sake of tuning, we report some findings that may help in the choice of the indexes to be defined and in the design of the filters:

  • Filters placed into a WorkitemNotFilter cannot be filtered using indexing. Therefore, indexing filters added to the Not Filter does not provide any speedup and may be counterproductive. Also, the use of this filter should be limited.
  • The indexes defined to support participant filters must be dropped if the extension configuration property participants.tracking.enabled is set to false and no custom logic is used to populate the participant attribute (see Participant Filters for more details).
  • In general, whenever an attribute contains the same value in the majority of cases, defining an index for that attribute is not recommended. An example could be defining an index on the token status to index WorkitemReadyOrActiveFilter, when the number of Workitems in a status different than Ready or Active is negligible.

In general, although some indexes may lead to a sub-optimal runtime, the execution of the Process:FindWorkitems Script Function using indexing should be faster than executing it without indexing.