Custom Filter

Target audience: Developers

Introduction

Sometimes, users want to see slightly different data than the default filters. These default filters show the work instances or tasks that you have permission on. There is also an API consuming filters available to search work items (i.e. root case or process instances) or a similar API for tasks. By default, the filterIds open, all, completed,mineand assignee are provided. However, sometimes there is no filter available which is giving you exactly what you would like to have.

In this case, Flowable offers you to create your own filter. In this howto, we'll show a basic example how such a custom filter can be built.

Filters can be created for

• Work lists (root process and case instances)
• Task lists v3.16.0+

Creating a custom filter

A Custom Filter needs to be defined to extend the default Work filters. These custom filters are JSON files that are put on the classpath in the location

• For work filters: com/flowable/filters/work/custom/
• For task filters: com/flowable/filters/task/custom/

These custom filter files are read and processed on server bootup. Thus when changes are needed, a server reboot is required.

There are 3 different types of filter. All 3 contain the following properties:

{
  "key": "basicFilterId",
  "type": "basic",
  "label": "By Basic",
  "labelKey": "translation.reference",
  "order": 20,
  "userGroupKeys": [
    "flowableUser"
  ],
  "userDefinitionKeys": [
    "user-admin"
  ]
}

• key
  • is a unique identifier for the filter
• type
  • required type property Values can be basic,query or alias
• label
  • the default label used for this filter
• labelKey
  • translation identifier to support multiple languages
• order
  • numeric (Integer) value for the order within all defined filter. The default value is '0'
• userGroupKeys
  • String list of all user groups with access to this filter
• userDefinitionKeys
  • String list of all user definition keys with access to this filter

NOTE: Users can see a filter if their UserDefinitionKey matches one of the defined, or one of their assigned UserGroups matches one of the defined UserGroups in the filter.

Different types of filter

Basic filter

Basic filter can be used without ElasticSearch. In addition, this type of filter provides a list of parameters to filter the work instances.

{
  "key": "basicFilterId",
  "type": "basic",
  "label": "Basic Filter",
  "labelKey": "translation.reference",
  "order": 2,
  "userGroupKeys": [
    "flowableUser"
  ],
  "userDefinitionKeys": [
    "user-admin"
  ],
  "parameters": {
    "definitionKey": "yourProcessDefinitionKey",
    "startUserId": "{currentUserId}"
  }
}

Work Filter Parameters

Possible parameters for work data are:

Parameter	Type
name	String
state	String
definitionId	String
definitionKey	String
definitionName	String
definitionCategories	List of Strings
definitionCategory	String
type	String
startUserId	String
assigneeUserId	String
finished	Boolean

Note: startUserId and assigneeUserId are capable of processing the expression {currentUserId}

Task Filter Parameters

Possible parameters for task data are:

Parameter	Type
name	String
completed	Boolean
assigneeUserId	String
ownerUserId	String
unassigned	Boolean
formKey	String
category	String
searchText	String
caseDefinitionId	String
caseDefinitionKey	String
caseDefinitionName	String
caseDefinitionCategory	List of Strings
caseDefinitionCategories	List of Strings
processDefinitionId	String
processDefinitionKey	String
processDefinitionName	String
processDefinitionName	List of Strings
processDefinitionCategories	List of Strings
scopeDefinitionId	String
scopeDefinitionKey	String
scopeDefinitionCategory	String
scopeDefinitionCategories	List of Strings
scopeType	String
sort	String (comma-separated when sorting on multiple fields)
sortOrder	String (comma-separated when sorting on multiple fields)

Index query filter

Query filters are used to integrate ElasticSearch index queries into the work UI. First you need to create a query as shown here, afterwards you can link this query to a filter. This works the same for work and task filters.

{
  "key": "filterId",
  "type": "query",
  "label": "Query Filter",
  "labelKey": "translation.reference",
  "order": 1,
  "userGroupKeys": [
    "flowableUser"
  ],
  "userDefinitionKeys": [
    "user-admin"
  ],
  "query": "yourQueryId",
  "queryParameters": {
    "customDefinitionKey": ""
  }
}

• query
  • Id of the query you want to execute
• queryParameters
  • parameters for the query

Index alias filter

Alias filters are used to integrate index aliases into the work UI. First you need to create a alias as shown here, afterwards you can link this alias to a filter. This works the same for work and task filters.

{
  "key": "filterId",
  "type": "alias",
  "label": "Alias Filter",
  "labelKey": "translation.reference",
  "order": 1,
  "userGroupKeys": [
    "flowableUser"
  ],
  "userDefinitionKeys": [
    "user-admin"
  ],
  "alias": "yourAlias"
}

• alias
  • the alias you want to execute

Default filters and overriding them

There are 5 default Work (basic) filters defined (assignee, open, mine, completed and all). Ordered like this with order values of 0, 10, 20, 30 and 40. You can integrate your own filter in between. If you want to override any filter, you just need to create a custom filter with the same id.

There are 5 default Task (basic) filters defined (mine, unassigned, open, completed and all). Ordered like this with order values of 0, 10, 20, 30 and 40. You can integrate your own filter in between. If you want to override any filter, you just need to create a custom filter with the same id.