Custom Filter

Target audience: Developers

Introduction

Sometimes, users want to see slightly different data than the default filters. These default filters, when you authenticate, show the work instances 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 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 for Work. In this howto, we'll show a basic example how such a custom filter can be built.

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 com/flowable/filters/work/custom/. These custom filter files are read 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, the BasicFilter 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}"
  }
}

• parameters
  • set of key-value pairs used to filter the work instances

possible parameters 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}'

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.

{
  "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.

{
  "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 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.