We are pleased to announce the next release of Camunda BPM 7.15, featuring the following improvements:
- Cockpit: Distinguish Between Canceled and Completed Process Instances (Enterprise)
- Cockpit: Detailed error message during deployment (Enterprise)
- Change the Header of your Webapps
- Tasklist: generic Forms allow Complex Data Types
- Revamped Unique Task Worker Metric
- External Task: Throw BPMN errors with expressions
- External Task REST API: Fail with Variables
- Skip failed Output Mapping on all Activities
- Extended OpenAPI documentation
- 12 Bug Fixes
You can Download Camunda for free or Run it with Docker.
For a complete list of all improvements, take a look at the release notes. Please also see the list of known issues.
If you want to dig deeper, you can find the source code on GitHub.
Cockpit: Distinguish Between Canceled and Completed Process Instances
This feature is only available in the Enterprise Edition of the Camunda BPM platform. Test it out with a Free Trial
So far, it’s not been possible to distinguish between completed and canceled process instances using the “Process Instances” tab on the process definition history page, with canceled process instances displayed as completed. This release makes it possible to differentiate between canceled and completed process instances.
In the “Process Instances” tab in the “State” column, Cockpit now distinguishes between:
- Running
- Completed
- Canceled externally — canceled by a user operation
- Canceled internally — canceled by an interrupting boundary event of the parent process instance’s call activity
Also, we introduced new filter criteria, “State” and “With Incidents”, so you can filter the list of process instances accordingly.
Cockpit: Detailed error message during deployment
This feature is only available in the Enterprise Edition of the Camunda BPM platform. Test it out with a Free Trial
When deploying files using Camunda Cockpit, you now get detailed error messages when the deployment fails. This helps identify problems in your models and resolve them faster. To test it out, head over to the Cockpit deployment Page.
Change the Header of your Webapps
You can now change the Vendor and Appname of all Webapps to adjust them to your brand. To do this, adjust the config.js located in app/{cockpit|admin|tasklist}/scripts and add the following configuration:
// …
app: {
name: 'Operations',
vendor: 'Company'
},
// …This will change the Brandname in the header to the name and vendor you selected.
Find out more about Webapp customizations, checkout our documentation.
Tasklist: generic Forms allow Complex Data Types
When debugging a process, it might be necessary to start it with certain process variables. To make it easier to debug and troubleshoot processes without embedded forms, the generic forms now allow you to add Variables of Type Object as well as File Uploads.
Generic Forms are the default for User Tasks and start events when you don’t add a custom form.
Revamped Unique Task Worker Metric
The process engine reports runtime metrics to the database that can help Camunda draw conclusions about usage, load, and performance of the BPM platform. One of those metrics is the Unique Task Worker (UTW) count. It identifies the number of unique users that were assigned to user tasks in a given period of time.
Previously, this metric was aggregated from history data, looking at the assignees of historic task instances that fell into the requested time span. This could pose restrictions on history cleanup and writing history data in general, in case this measure must be retrieved reliably – for enterprise customers, the license agreement could require them to report this metric and therefore also have implications on this data specifically.
With this release, this metric is now based on data gathered in a new, separate table. It will comprise the timestamp of an assignment and a pseudonymized, fixed-length hash value of the assignee, to keep the data to a reasonable minimum but still insightful enough to reliably aggregate the metric.
The metric can still be retrieved via the Admin Webapp and additionally, it can now also be fetched via REST API providing the metrics name unique-task-workers. In case the metric is not required to be reported and of no further interest, it can also be disabled via a new engine configuration option taskMetricsEnabled. You can consult our Metrics Guide to see how to achieve that.
Furthermore, the new data can also be cleaned up automatically via history cleanup if the engine configuration property taskMetricsTimeToLive is configured to a specific number of days. See our History Cleanup Guide for more details. If you would like to clean up the metrics data manually, e.g. after reporting it according to the license agreement, you can use the all-new REST API for that as well.
External Task: Throw BPMN errors with expressions
With BPMN error throw and catch events, it’s possible to perform error handling within the BPMN model by throwing an error in one activity and catching it somewhere else.
This is also possible with external tasks by calling the /bpmnErrorREST endpoint. But what if the client that executed the task can’t tell if a result is an error?
Example: Let’s say we implemented an External Task that should be handled by the Camunda Platform RPA Bridge. The task is forwarded to an RPA vendor and the result is received in the Bridge. The RPA vendor does not know about the BPMN process running in the Camunda Platform. Based on the result, we need to decide if the External Task executed as expected, an error (that should be handled by the BPMN error concept) needs to be raised, or if the Task should be retried (or an incident created in case of no retries left).
In the example above it makes sense to decide the result of the External Task in Camunda Platform rather than in an External Task client like Camunda Platform RPA Bridge. This is why we decided to introduce camunda:errorEventDefinition, an extension attribute for external Service Tasks. It extends the common bpmn:errorEventDefinition by an additional expression attribute. The expression is evaluated on complete and failure of the External Task. If the expression evaluates to true, the activity is canceled and a BPMN error is thrown. If it evaluates to false, or if the expression is empty the default behavior (based on whether the task was completed/failed) is executed.
Additionally, with this change it is possible to access the ExternalTaskEntity object from any expression in the scope of an External Service Task Activity by the identifier externalTask. This object gives you access to errorDetails, workerId, retries, and more. Read more in the Expression Language User Guide and the Javadocs.
This feature also works well with the next topic in this Release Blog Post — External Task REST API: Fail with Variables. Those variables are also available for expressions in External Tasks. Check out the next topic for details.
Examples:
How do I access the External Task object and match an error message coming from my bot?
<bpmn:serviceTask id="myRPAtask" name="GenerateReceipt" camunda:type="external" camunda:topic="RPA">
<bpmn:extensionElements>
<camunda:errorEventDefinition id="myErrorEventDefinition" errorRef="myError" expression="${externalTask.getErrorDetails() == 'myErrorMessage'}" />
<camunda:properties>
<camunda:property name="bot" value="PrintReceipt" />
</camunda:properties>
</bpmn:extensionElements>
</bpmn:serviceTask>How can I match a substring?
Note that if multiple errorEventDefinitions are provided, the first one that evaluates to true will trigger the referenced error. In this example, myErrorEventDefinition1 and myErrorEventDefinition2 will trigger the same error, while myErrorEventDefinition3 will trigger a different one:
<bpmn:serviceTask id="myRPAtask" name="GenerateReceipt" camunda:type="external" camunda:topic="RPA">
<bpmn:extensionElements>
<camunda:errorEventDefinition id="myErrorEventDefinition1" errorRef="myError" expression="${myStringVar.startsWith('foo'}" />
<camunda:errorEventDefinition id="myErrorEventDefinition2" errorRef="myError" expression="${myStringVar.endsWith('bar'}" />
<camunda:errorEventDefinition id="myErrorEventDefinition3" errorRef="myError2" expression="${myStringVar.contains('baz'}" />
</bpmn:extensionElements>
</bpmn:serviceTask>If you want to know more about this feature, please read the section about error handling in the Expression Language User Guide and in the Camunda Platform RPA Bridge.
External Task REST API: Fail with Variables
With this release it is possible to pass variables when failing an External Task (e.g. through the REST API).
This is especially useful when used with the previously discussed camunda:errorEventDefinition expression, as those variables are then available in the expression and allow for a much more fine-grained error handling (e.g. throw error A if the errorDetails contain “myError”, but throw error B if they don’t).
Skip failed Output Mapping on all Activities
Output mapping is used to make local variables in one scope available in the parent scope. For example, a local variable in a Task can be mapped to a variable that is available in the process instance by using output mapping.
<camunda:inputOutput>
<camunda:outputParameter name="myProcessVariable">${myLocalTaskVariabl}</camunda:outputParameter>
</camunda:inputOutput>Since this behavior is hard-coded into the BPMN model, it can happen that a variable is not available even though it is defined as an output parameter. A good example for such a case is when passing variables from an External Task. The engine can not control what variables will be received — there even might be different variables based on the result of the Task.
With the expanded External Task Failure REST API it is possible to pass variables when failing the External Task. Since this can be a completely different variable set compared to a successfully completed External Task we need to make sure that the process instance can continue even when not all expected variables are available.
With this release, there is a new engine configuration flag called skipOutputMappingOnCanceledActivities, which is false by default. When set to true, the engine will ignore failures when mapping output parameters. This means there will be no errors when a variable is not available. However, it also means that you cannot rely on the existence of said variable later in the process.
The new flag can be used whenever it is necessary to map variables to their parent scope without knowing if said variables will be available at execution time.
Extended OpenAPI documentation
We added OpenAPI descriptions for the following REST API endpoints:
ExecutionJobVariable Instance
To learn more about our OpenAPI, visit our official documentation.
Share Your Thoughts with Us!
Your feedback is really important to us, so please download Camunda BPM 7.15.0-alpha3, try it out, and let us know what you think about it.
You can contact us in the forum, send a tweet to @Camunda, or file a bug in our ticket system.
