Flowable Work Form Expressions

Outdated documentation page

This is an old version of the documentation for Flowable until version 3.13 and for the Angular-based Flowable Design 3.14/3.15. If you are running the latest version of Flowable please check out the current version of this page.

Exposed Endpoints

In Flowable Work Form the endpoints can be retrieved with the following binding: {{endpoints.xxx}}.

This variable is a dictionary object of the endpoints available to the forms inside expressions.

Endpoint name	Default value	Description
baseUrl	(undefined)	When only the baseUrl is configured, then the rest of endpoints are built based on the baseUrl as the url prefix. Otherwise, their configured value will be used as is.
action	action-api
engage	engage-api
form	form-api
idm	idm-api
report	platform-api/reports
cmmn	cmmn-api
process	process-api
platform	platform-api
login	auth/login
logout	auth/logout
auth	auth
content	content-api
dmn	dmn-api
dataobject	dataobject-api
audit	audit-api
actuator	actuator
template	template-api
inspect	inspect-api

note

For Work and Engage the value of all these endpoints can be configured manually through an application.properties change at the backend, for example with: flowable.frontend.endpoints.baseUrl = /flowable-work.

Furthermore, this dictionary of endpoints can be enhanced in a customized frontend through the additionalData.endpoints object, which you can extend in your src/index.tsx as follows:

export default {
    additionalData: {
        endpoints: (defaultEndpoints) => {
            ...defaultEndpoints,
            myCustomExternalApi: 'http://custom-api/whatever'
        }
    }
};

note

Alternatively, when using Flowable Work or Engage, you can define new endpoints available to the frontend through a Spring application property like: flowable.frontend.endpoints.myCustomExternalApi=http://custom-api/whatever

If baseUrl is set to /flowable-work and no additional endpoint is configured, then the endpoints object looks like:

"endpoints": {
    "baseUrl": "/flowable-work",
    "action": "/flowable-work/action-api",
    "engage": "/flowable-work/engage-api",
    "form": "/flowable-work/form-api",
    "idm": "/flowable-work/idm-api",
    "report": "/flowable-work/platform-api/reports",
    "cmmn": "/flowable-work/cmmn-api",
    "process": "/flowable-work/process-api",
    "platform": "/flowable-work/platform-api",
    "login": "/flowable-work/auth/login",
    "logout": "/flowable-work/auth/logout",
    "auth": "/flowable-work/auth",
    "content": "/flowable-work/content-api",
    "dmn": "/flowable-work/dmn-api",
    "dataobject": "/flowable-work/dataobject-api",
    "audit": "/flowable-work/platform-api",
    "actuator": "/flowable-work/actuator",
    "template": "/flowable-work/template-api",
    "inspect": "/flowable-work/inspect-api"
}

The endpoints dictionary is particularly useful when modelling urls of calls to the backend. For example, with the following Datatable Query URL value:

{{endpoints.platform}}/search/work-instances?size={{$pageSize}}&start={{$start}}&{{$sort}}&{{$filter}}

As shown above, when configuring baseUrl to /flowable-work, the {{endpoints.platform}} will resolve into /flowable-work/platform-api, and, for the previous example, the network request to fetch the data will use a query url like:

http://your-server-hostname/flowable-work/platform-api/search/work-instances?size=10&start=0

But if the resolved Query URL does not start with / or http|s://, for example if it resolves to platform-api/search/work-instances?size=10&start=0 then your server context (location.pathname) will be used instead. As an example if your Tomcat root context is work, then the resulting query url to fetch the data will look like:

http://your-server-hostname/work/platform-api/search/work-instances?size=10&start=0

or if there is no root context:

http://your-server-hostname/platform-api/search/work-instances?size=10&start=0

Current User Information

This variable $currentUser in the Flowable Work frontend contains information about the currently logged-in user.

$currentUser: {
  id: "sherlock.holmes",
  firstName: "Sherlock",
  lastName: "Holmes",
  displayName: "Sherlock Holmes",
  email: "curator@sherlock-holmes.co.uk",
  ...
}

It can be enhanced in a customized frontend through the additionalData.$currentUser object, which you can extend in your src/index.tsx as follows:

export default {
  additionalData: {
    $currentUser: (currentUser) => {
      var userInitials =
        currentUser.firstName.charAt(0).toUpperCase() +
        currentUser.lastName.charAt(0).toUpperCase();
      return {
        ...currentUser,
        initials: userInitials,
        canInvestigate: () => currentUser.id == "sherlock.holmes",
      };
    },
  },
};

Retrieval of User Information

This expression is a new feature introduced as of Flowable Work version v3.10.0+ in which you can retrieve the information of any user given its id.

Internally, makes an API call to retrieve the whole user object, so you can use any property inside of the user retrieved.

For example:

// Retrieve the user information for a given userId.
{{flw.getUser('userId').displayName}}

This expression under the hood it's built with a performant cache, which means that if you call in the same page the same expression with the same arguments, will request to the backend only a single time the resource.

Usually this concept is a common functionality to transform a userId to any other attribute of the user, e. g. the Display Name, when showing it into a data table row. Therefore, the Data component section is filled with a htmlComponent.

For example:

{
    "type": "htmlComponent",
    "value": "<span>{{flw.getUser($item.userId).displayName}}</span>"
}

Retrieval of Master Instances

The getMasterDataInstance expression is a new feature introduced as of Flowable Work version v3.10.0+ in which you can retrieve the information of any master data instance given its id.

{{flw.getMasterDataInstance('masterDataInstanceId').name}}

The getMasterDataInstanceByKey expression is a new feature introduced as of Flowable Work version v3.14.1+ in which you can retrieve the information of any master data instance given its masterDataInstanceKey and the masterDataDefinitionKey.

// Retrieval of the master data instance object based on masterDataInstanceKey and masterDataDefinitionKey. 
{{flw.getMasterDataInstanceByKey('masterDataInstanceKey', 'masterDataDefinitionKey').name}}

Retrieve Data Object Instances

This expression is a new feature introduced as of Flowable Work version v3.11.7+ in which you can retrieve the information of any data object instance.

// Retrieval of the data object instance based on dataObjectDefinitionKey, dataObjectOperationKey, dataObjectLookupKey and dataObjectLookupValue
{{flw.getDataObjectInstance('dataObjectDefinitionKey', 'dataObjectOperationKey', 'dataObjectLookupKey', 'dataObjectLookupValue').variableOne}}

Validation and Validation Errors

This expression is a new feature introduced in Flowable Work version v3.12.0+ and when called will trigger a validation of the component with the id passed as parameter (if undefined will trigger a validation of the entire form) and return an array of validation errors:

// validation triggered only for one component, where the id matches to 'componentId'
{{flw.validate('componentId')}}

// validation for the entire form
{{flw.validate()}} 

[
    {
        $computedPath: ".extraSettings.layoutDefinition.rows.0.cols.0",
        $errors: ['invalidFiles'],
        id: "attachment1",
        validationMessages: ['There are invalid files attached.']
    },
    {
        $computedPath: ".extraSettings.layoutDefinition.rows.1.cols.0",
        $errors: ['maxFiles'],
        id: "attachment2",
        validationMessages: ['The number of files that can be added is 2']
    },
    {
        $computedPath: ".extraSettings.layoutDefinition.rows.2.cols.0",
        $errors: ['isRequired'],
        id: "text1",
        validationMessages: ['Field must not be empty']
    }
]