Developer Guide
Key Terms
BPMN
Business Process Model and Notation (BPMN) allows you to visualize your internal procedures using a graphical representation. It also facilitates clear communication of these processes in a standardized format across your organization.
Models
In Camunda BPMN, a workflow model is a graphical representation of a business process using the Business Process Model and Notation (BPMN) standard. This model includes various elements such as tasks, events, gateways, and flows that define the sequence and logic of the process.
You can build these models using the Camunda Model, ensuring they meet BPMN 2.0 standards. After publishing, it can be used to launch workflows.
Task
This refers to a small unit of work defined within a model that must be completed as part of the overall workflow. For example, you can use a receive task to wait for a notification message indicating that a new batch of samples has arrived at the laboratory. Once you receive the message, the workflow proceeds to the next steps.
Events
Events serve as triggers within a workflow that influence process behaviour. For instance, start events initiate a process, Timer events handle time-based actions like sending reminders, and Error events manage exceptions.
Supported Tasks and Events
You can build the BPMN model using the tasks and events listed below. While modelling, make sure to give each task and event an appropriate name.
- Send Task
- Receive Task
- Service Task
- Script Task
- Manual Task
- Business Rule Task
Publish BPMN model in LDAS
An External API user can publish a BPMN model. Currently, models can only be published in LDAS through an API call. Using the URL provided in the table below, you can generate an authorization token and a refresh token to publish the model in LDAS.
| Field | Value Description |
|---|---|
| URL | <LDAS DNS>/api/user/authentication/external/user |
| Method | POST |
| Header | - |
| Authorization | - |
| Request parameters |
username – name of the user created in LDAS with “External API user” role password – encrypted password of the user. |
Table 4 Details for generating authorization token and refresh token
Once the authorization token is generated, the model can be published in LDAS within any specific organization path using the details provided in the table below.
| Field | Description |
|---|---|
| URL | <LDAS DNS>/api /model/publish |
| Method | POST |
| Authorization | <the bearer token from the authorization endpoint> |
| Headers |
|
| Request Parameters |
|
Table 5 Details for publishing the BPMN model in LDAS
When using the "publish model" API, ensure the model name matches the process name defined in the BPMN model. Duplicate model names are not allowed within the same path but are permitted in parallel paths.
The Process Definition Key in the model file must be unique for each model. If you publish a model with the same Process Definition Key again in the same organization path, it will be treated as a version increment of the existing model. To view a sample request for the "publish model" API, refer to the figure below.
Figure 8 Sample request to publish a model
Once the model is successfully published within LDAS, the External API user will receive a success response.
If the model publishing fails, the External API user will receive a failure response along with the reason for the failure.
The table below provides a list of the various response codes, along with the potential failure reasons and corresponding messages that can be expected for those reasons.
| Response Code | Reason | Message |
|---|---|---|
| 200 | Success | Model published successfully. |
| 400 | Model name/ organization path name is empty | Invalid request, please provide the mandatory fields |
| 400 | File not sent | File missing in the request |
| 500 | Unsupported file format | Could not parse BPMN process: File format not supported. |
| 400 | Invalid Organization path | Error occurred while getting Organization path id for Organization path name |
| 400 | Model with same process ID in bpmn file is published again | Model with the same Process ID already exists |
| 400 | Process name is empty in model file | Process name in the bpmn file cannot be empty |
| 400 | Model name and process name in bpmn file mismatches | Model name doesn't match the process name in the bpmn file |
| 400 | Model name contains special char(/) | Model name cannot contain special character '/' |
| 400 | Model name exceeds 250 characters | Model name should not exceed 250 characters. |
| 400 | File name already exist in the Organization Path | Model name already exist. |
| 504 | Internal server Error | An unexpected error occurred. Please contact System Administrator |
Table 6 Response while publishing the model.
Workflow Configuration Details
If there’s any important information about the workflow, like sample details, experiment names, or files, you can view this information in multiple sections within the Workflow Parameters section, and any files can be found in the Attachment section in LDAS.
To enable this, configure the information under the z_mappingConfig variable when creating a model. Typically, this is defined as "Form fields" within the Start Event of a model. If it's not configured within the model, you can define some of this information as a "variable" in the API request when you launch a workflow.
Figure 9 Configuring z_mappingConfig in start event
Customizing Workflow ID
If you need to set any custom ID for a workflow, you can do so by defining them in the z_workflowIdKey variable as "Form fields" within the Start Event of a model. If the z_workflowIdKey is not provided with a value while launching the workflow through API, then LDAS will throw an error response requesting for the same.
Customizing Workflow Status
If you need to set any additional custom statuses for a workflow that is in progress, you can do so by defining them in the z_workflowStatus variable. Just make sure not to use any of the existing statuses listed in the table below within your custom statuses.The table below highlights the differences between workflow status and Camunda status.
| Workflow Status | Camunda Status |
|---|---|
| InProgress | Active |
| Completed | Completed |
| Suspended | Suspended |
| Cancelled | Externally terminated |
| Failed | Internally terminated |
| Active with incidents | Externally terminated with incident |
You can add z_workflowStatus as a ‘Process Variable Name’ within the Output Parameters of a specific task. Once the task is completed, the workflow status will be updated based on the custom status you’ve defined in the Variable Assignment Value.
Figure 10 Configuring z_workflowStatus in output parameters
The custom statuses you’ve defined within the BPMN model will be displayed in the LDAS workflow as shown below.
Figure 11 Configured custom status is now the status for the next task
Workflow Launch
A workflow can be started either from an external system or by initiating it through an already generated activity.Workflows in LDAS are always launched using the latest version of the model. If a model is modified by adding, modifying, or deleting tasks and then republished with the same name and Process Definition Key, it is considered a new version of the old model. Therefore, workflows launched after this will use the latest version of the model.In order to edit and utilize it as a new model, it must be created as a new BPMN file with a unique Process Definition Key.
Note:
When a model is published in the parent organization path, workflows can be launched at that level or from any of its child organization paths.
The following details are required to launch a workflow using an API REST call:
| Field | Description |
|---|---|
| URL | <LDAS DNS>/api/automation/workflows/launch/start-process/modelname |
| Method | POST |
| Authorization | <the bearer token from the authorization endpoint> |
| Headers |
|
| Request Parameters |
|
Table 7 Details for starting the workflow with the developed BPMN model using model name.
Figure 12 Sample request for start workflow
The table below provides the different response codes, along with the reasons for failure and the expected messages associated with each code.
| Response Code | Reason | Message |
|---|---|---|
| 200 | Success | Workflow launched successfully |
| 400 | Empty Model name | Model name is empty, Please provide Model name |
| 400 | Empty Organization path | Organization Path is empty, Please provide Organization Path |
| 400 | Invalid model name/Model not associated to the Organization path | Model does not exist in the given organization path |
| 400 | Invalid Organization path | Error occurred while getting Organization path id for Organization path name |
| 500 | Internal server Error | Error occurred while launching workflow |
| 400 | Value of z_workflowIdKey is empty in the model | Cannot launch workflow since z_workflowIdKey's value is empty in the model |
| 400 | z_workflowIdKey is given in the model, but the corresponding key is not provided in the request | Cannot launch workflow since <workflow_IDkey> is not provided under the request variables |
| 400 | External Id value is not provided in the request | Cannot launch workflow since the value of <workflow_IDkey> is empty |
| 400 | Duplicate Workflow ID is provided in the request | Cannot launch workflow since there already exists a workflow with workflowId |
Figure 13 Response while starting the workflow using model name
Complete Message events/Receive Task within a workflow
To complete a message task or message event within a workflow, the "complete message event/task" API is used. The message name must be specified in the API and must exactly match the name assigned to that task or event in the model (case-sensitive) to complete it.
| Field | Description |
|---|---|
| URL | <LDASDNS>/api/orchestration/workflows/instrument/file |
| Method | POST |
| Authorization | <the bearer token from the authorization endpoint> |
| Headers |
|
| Request Parameters |
|
Table 8 Details for adding the file to the launched workflow.
Figure 14 Sample request for add a file to workflow
The table below provides the different response codes, along with the reasons for failure and the expected messages associated with each code.
| Response Code | Reason | Message |
|---|---|---|
| 200 | Success | Message event completed successfully |
| 400 | Empty Model name | Model name is empty, Please provide Model name |
| 400 | Empty Organization path | Organization Path is empty, Please provide Organization Path |
| 400 | variablesInResultEnabled as true and resultEnabled as false | The variablesInResultEnabled cannot be true when resultEnabled is false |
| 400 | Empty message | Message Name is empty, Please provide the Message Name |
| 400 | Message name not found in camunda | Message not found |
| 400 | Empty Workflow Number | Workflow Number is empty, Please provide the Workflow Number |
| 400 | No model found in Organization path | Model does not exist in the given organization path |
| 400 | No workflow exists | Workflow does not exist in the given organization path |
| 404 | Invalid Organization path | Model not found in the given Organization Path |
| 400 | Invalid Organization path | Error occurred while getting Organization path id for Organization path name |
| 500 | Internal server Error | An unexpected error occurred. Please contact System Administrator. |
Table 9 Response while starting the workflow using model name
Updated 12 days ago