Process-App

Introduction

This topic provides you with general information about the process app API, its scope of functions and useful information to know when programming functions and customizations.

Scope of functions of the process app

The process app allows you to automate business processes. You can allow users to participate in processes in the form of tasks or perform automated service activities. The process app supports the BPMN standard. This gives you many options when designing processes.

In process monitoring, you have the option to check the status of active processes. If an error occurs, you have the option to apply corrections directly. This is a simple way to ensure the successful execution of your business processes. The process administration allows you to execute actions across several process instances. For example, you can cancel several process instances, migrate them to a new version in case of process changes, rerun failed process instances or delete a process version.

If you have modeled your own process, you can deploy it in the process administration. The process will then be available to you in the d.3ecm world.

Technical background information

The process app uses an HTTP interface for the deployment of public API functions that can be accessed using the base address of the HTTP gateway app. Authentication with the identity provider app is required in most cases to use these functions.

Using the API functions

In the following chapters, you can learn more about the various options for using the process app user interfaces to meet your requirements. All listed URIs relatively refer to the URI of the process app '/process'.

Authentication

Some API functions of the process app require a valid authentication from the identity provider app.

Refer to the API documentation the identity provider app to find out how to obtain such an authentication.

Deploying processes

You can use this HTTP interface to deploy a process. The use of this interface requires authentication with the identity provider app. The user requires the role Process user.

The deployment of processes consists of three steps:

  1. Create a deployment.
  2. Add BPMN.
  3. Activate the deployment.

Creating the deployment

A deployment is a process intended for later activation. As long as a deployment is not activated, the process cannot be started.

Use the following request to create a deployment:

Request

POST /process/deployment
Accept: application/json

{
    "source" : "app-123",
    "_links" : {
        "processSource" : {
            "href" : "/app-123/deployments/my-deployment-1"
        }
    }
}

Notes on the content

You can include the data of the deployment to be created in the content.

  • source: The source from which the deployment originates, e.g. the name of the app providing the deployment. Required field. The value may not be empty and can contain a maximum of 255 characters. Permitted characters are: a-z, 0-9, -.
  • _links:
    • processSource: The URI that can be used to query the deployment. The process app saves process definitions as BPMN only. This URI serves to provide the process definition in the form in which it was created. This URI should be permanently available and should represent the process definition in exactly the version it was in at the time of the deployment. Optional.

Returned values for the request

  • 201: Success. The deployment was created and saved for later processing and activation.
  • 400: The request is invalid. Please refer to the note on content.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to create a deployment.

The HTTP status code 201 is returned in case of success. The location header will then contain the URI that you can use to query the deployment. In addition, the deployment is already contained in the body. You can use the link bpmnUri of the body to add the BPMN directly.

Querying the deployment

You can query a deployment in order to find out if it is valid and which URI you can use to activate it. The validity depends on whether the contained process is BPMN-compliant. You can query a deployment in two formats: as JSON or HTML. The HTML representation is a dialog in which you can activate the deployment via a user interface.

Querying the deployment in JSON format

Query the deployment in JSON format as follows:

GET /{Deployment Location Header-URI}
Accept: application/json, application/hal+json

Replace the placeholder {Deployment Location Header URI} with the URI from the location header that was returned when the deployment was created.

If the deployment is valid, the following JSON is returned:

Response

{
    "type": "BPMN",
    "valid": true,
    "_links":{
        "activation":{
            "href": "/process/deployment/randomId/activate"
        },
        "bpmn" : {
            "href" : "/process/deployment/randomId/staging/bpmn"
        },
        "processSource" : {
            "href" : "/app-123/deployments/my-deployment-1"
        }
    }
}

Notes on the links

  • bpmn: You can use this link relation to add the BPMN to the deployment.
  • activation: You can use this link relation to activate the deployment. This link is only available if the deployment is valid.

If the deployment is invalid, the following JSON is returned:

Response

{
    "type": "BPMN",
    "valid": false,
    "invalidReason": "Process deployment is invalid: Process with ID 'myProcessId' but another capitalization already exists",
    "invalidReasonKey": "idMismatch"
}

The parameter invalidReasonKey identifies the reason for the invalidity of the deployment in machine-readable form if the reason can be specified. In case of unspecified reasons, such as an error during parsing of the BPMN XML, this parameter is not contained in the response. Possible values currently are:

  • mixedOperation: This error means that the process to be deployed already exists as a single-use process.
  • idMismatch: This error means that a process with this ID already exists with a different capitalization.
  • userTaskAssignment: This error means that the rules for the assignment of recipients regarding the humanPerformer and potentialOwner constructs were not observed.
  • invalidBpmn: This error means that an invalid BPMN model was uploaded.
  • unknown: This error means that the reason cannot be specified further.

Querying the deployment in HTML format

Query the deployment in HTML format as follows:

Request

GET /{Deployment Location Header-URI}
Accept: text/html

A HTML page is returned that indicates whether the deployment is valid. You can use this HTML page to activate the deployment.

Returned values for the request

  • 200: Success. The deployment is already contained as HTML or JSON in the body.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to query the deployment.
  • 404: The deployment does not exist.

Add BPMN.

You can add the BPMN process to the deployment using a separate URI.

Request

PUT /{Deployment bpmn-URI}
Content-Type: application/bpmn

BPMN XML content of a process

Notes on the content

The content must contain valid BPMN with a maximum size of 1MB.

Returned values for the request

  • 200: The BPMN was added to the deployment.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to edit a deployment.
  • 404: The deployment does not exist.

Activating the deployment.

If a deployment is valid, you can activate it. You can then run the process. After successful activation, the deployment is no longer available and you cannot query it.

Request

POST /{Deployment activation-URI}
Accept: application/json

{
    "protocol" : true,
    "exportProtocol" : false,
    "protocolRetentionTime" : "P30D",
    "processInstanceRetentionTime" : "P30D"
}

Notes on the content

You can include the following information in the content for the deployment to be activated.

  • protocol: If the value is true, a protocol is created for instances of the new process definition. If the value is false, you may not use any of the following parameters.
  • exportProtocol: If the value is true, the protocol is exported to the DMS app upon completion of the instance. In order to use this function, the protocol export must have been configured completely. In this case, you may not specify a retention time in the parameter protocolRetentionTime.
  • protocolRetentionTime: Specifies the duration for how long the protocol is kept in the system after the process is completed. You must specify this value, if exportProtocol has the value false. You must specify a value between 0 and 365 days in the ISO-8601 format. If you configure 0 days, the protocol is immediately deleted after completion of the process instance. This value must not be greater than the value of processInstanceRetentionTime (if it is greater than 0).

If you do not transfer content, the standard for the protocol configuration is used. This is the standard configuration: protocol=true, exportProtocol=false and protocolRetentionTime=P30D.

  • processInstanceRetentionTime: (Optional) Specifies the duration for how long the process instance is kept in the system after the process is completed. You must specify a value between 0 and 365 days in the ISO-8601 format. If you configure 0 days, the process instance is the process instance is deleted at the next possible point in time.

Returned values for the request

  • 200: The deployment was activated successfully.
  • 400: The deployment is invalid. This value is also returned if the combination of the transmitted definitions is illogical.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to activate the deployment.
  • 404: The deployment does not exist.
  • 409: A single-use process with the same ID has already been started.

Deleting the deployment

In case a deployment is not to be activated, you can delete it.

Use the following request to delete the deployment:

Request

DELETE /{Deployment Location Header-URI}

Returned values for the request

  • 200: The deployment was deleted successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to delete the deployment.
  • 404: The deployment does not exist.

Deploying single-use processes

You can use this HTTP interface to deploy a single-use process. The use of this interface requires authentication with the identity provider app. The owner requires the role Process user or Process administrator.

The single-use process is automatically removed from the system after one-time successful execution or cancellation. History data of the executed process instance is also removed upon completion or cancellation of the instance.

The case for deployment of processes consists of three steps:

  1. Create a deployment.
  2. Add BPMN.
  3. Activate the deployment and start the process.

Creating the deployment

A deployment is a process intended for later activation. As long as a deployment is not activated, the contained process is not available in the workflow module and therefore cannot be started.

Use the following request to create a deployment:

Request

POST /process/singleusedeployment
Content-Type: application/json

{
    "source" : "app-123",
    "_links" : {
        "processSource" : {
            "href" : "/app-123/deployments/my-deployment-1"
        }
    }
}

Notes on the content

You can include the data of the deployment to be created in the content.

  • source: The source from which the deployment originates, e.g. the name of the app providing the deployment. Required field. The value may not be empty. Permitted characters are: a-z, 0-9.
  • _links:
    • processSource: The URI that can be used to query the deployment. The process app saves process definitions as BPMN. This URI serves to provide the process definition in the form in which it was created. This URI should be permanently available and should represent the process definition in exactly the version it was in at the time of the deployment. Optional.

Returned values for the request

  • 201: Success. The deployment was created and saved for later processing and activation.
  • 400: The request is invalid. Please refer to the note on content.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to create a deployment.

The HTTP status code 201 is returned in case of success. The location header will then contain the URI that you can use to query the deployment. In addition, the deployment is already contained in the body. You can use the link bpmnUri of the body to add the BPMN directly.

Querying the deployment

You can query a deployment in order to find out if it is valid and which URI you can use to activate it. The validity depends on whether the contained process is BPMN-compliant.

Querying the deployment in JSON format

Query the deployment in JSON format as follows:

Request

GET /{Deployment Location Header-URI}
application/json, application/hal+json

Replace the placeholder {Deployment Location Header URI} with the URI from the location header that was returned when the deployment was created.

If the deployment is valid, the following JSON is returned:

Response

{
    "type": "BPMN",
    "valid": true,
    "_links":{
        "start":{
            "href": "/process/singleusedeployment/f4da94c4-41c1-44bb-9223-1cdfb18bbe24/start"
        },
        "bpmn" : {
            "href" : "/process/singleusedeployment/f4da94c4-41c1-44bb-9223-1cdfb18bbe24/staging/bpmn"
        },
        "processSource" : {
            "href" : "/app-123/deployments/my-deployment-1"
        }
    }
}

Notes on the links

  • bpmn: You can use this link relation to add the BPMN to the deployment.
  • start: You can use this link relation to activate and start the deployment. This link is only available if the deployment is valid.

If the deployment is invalid, the following JSON is returned:

Response

{
    "type": "BPMN",
    "valid": false,
    "invalidReason": "Process deployment is invalid: Process with ID 'myProcessId' but another capitalization already exists",
    "invalidReasonKey": "idMismatch"
}

The parameter invalidReasonKey identifies the reason for the invalidity of the deployment in machine-readable form if the reason can be specified. In case of unspecified reasons, such as an error during parsing of the BPMN XML, this parameter is not contained in the response. Possible values currently are:

  • mixedOperation: This error means that the single-use process to be deployed already exists as a permanently deployed process.
  • idMismatch: This error means that a process with this ID already exists with a different capitalization.
  • userTaskAssignment: This error means that the rules for the assignment of recipients regarding the humanPerformer and potentialOwner constructs were not observed.
  • invalidBpmn: This error means that an invalid BPMN model was uploaded.
  • unknown: This error means that the reason cannot be specified further.

Returned values for the request

  • 201: Success. The deployment is already contained as JSON in the body.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to query a deployment.
  • 404: The deployment does not exist.

Add BPMN.

You can add the BPMN process to the deployment using a separate URI.

Request

PUT /{Deployment bpmn-URI}
Content-Type: application/bpmn

BPMN XML content of a process

Notes on the content

The content must contain valid BPMN with a maximum size of 1MB.

Returned values for the request

  • 200: The BPMN was added to the deployment.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to edit a deployment.
  • 404: The deployment does not exist.

Activating the deployment and starting the process

If a deployment is valid, you can activate it and start the process. With the activation, the contained process is deployed in the workflow module and then started. After successful activation, the deployment is no longer available and you cannot query it.

Request

POST /{Deployment start-URI}
Content-Type: application/json

{
    "businessKey" : "myBusinessKey",
    "correlationKey" : "myCorrelationKey",
    "variables" : {
        "variable_1" : "value"
    },
    "_links" : {
        "endCallback" : {
            "href" : "/myapp/callback"
        }
    }
}

Replace the placeholder {Deployment start URI} with the start URI which was returned when the deployment was queried.

Notes on the content

  • businessKey: Business key for the process instance. A business key is a freely assignable external key which can be used to identify the process instance. The business key does not play any role during runtime (optional, max. 255 characters).
  • correlationKey: The correlation key ensures that only one process instance is started for this unique key. If a process instance with the transferred key already exists, the system does not start a new process and the code 201 is transferred nevertheless. The process instance which should be started must be identical in content to an already existing process instance with the same correlation key (optional, max. 255 characters).
  • variables: Initial process variables (optional). For more information on the format, see section Basic information about process variables.
  • _links: Links (optional).

Possible links

The URI endCallback is called when the process instance is successfully completed or cancelled with the HTTP POST request. The call is identical to the case under Starting processes.

Returned values for the request

  • 201: The deployment was activated successfully and the process was started. The process instance URI is in the Location header.
  • 400: The deployment or the process variables are invalid. Maybe the correlation key was already used for another but not identical process start.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to activate the deployment.
  • 404: The deployment does not exist.
  • 409: A process with the same ID has already been started permanently.

If starting the process fails, e.g. due to invalid variables, the deployment will subsequently remain. You can try to rerun the activation and/or the start. If you want to discard the deployment, it needs to be deleted accordingly by the client.

Deleting the deployment

In case a deployment is not to be activated, you can delete it.

Use the following request to delete a deployment:

Request

DELETE /{Deployment Location Header-URI}

Returned values for the request

  • 200: The deployment was deleted successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to delete a deployment.
  • 404: The deployment does not exist.

Starting processes

You can use this HTTP interface to start a process. The use of this interface requires authentication.

Use the following request to start a process:

Request

POST /process/processes/{processId}/instances
Content-Type: application/json

{
    "businessKey" : "myBusinessKey",
    "correlationKey" : "myCorrelationKey"
    "variables" : {
        "variable_1" : "value"
    },
    "_links" : {
        "endCallback" : {
            "href" : "/myapp/endCallback"
        },
        "incidentCallback" : {
            "href" : "/myapp/incidentCallback"
        }
    }
}

If starting without authentication is configured for this process, you can use this HTTP interface instead:

POST /process/anonymous/processes/{processId}/instances
Content-Type: application/json

{
    "businessKey" : "myBusinessKey",
    "correlationKey" : "myCorrelationKey"
    "variables" : {
        "variable_1" : "value"
    }
}

When starting without authentication, the response does not contain a location header.

The parameters endCallback and incidentCallback are not permitted when starting the process without authentication.

Replace the placeholder with the ID of the process definition.

Notes on the content

  • businessKey: Business key for the process instance. A business key is a freely assignable external key which can be used to identify the process instance in process monitoring (optional, max. 255 characters).
  • correlationKey: The correlation key ensures that only one process instance is started for this unique key. If a process instance with the transferred key already exists, the system does not start a new process and the code 201 is transferred nevertheless. The process instance which should be started must be identical in content to an already existing process instance with the same correlation key (optional, max. 255 characters).
  • variables: Initial process variables (optional). For more information on the valid variables, see section Basic information about process variables.
  • _links: Links (optional).

Possible links

The URI endCallback is called when the process instance is successfully completed or cancelled with the HTTP POST request. If the target address follows the base address, the call is authenticated. The process app uses the app user "process@app.idp.d-velop.local" for the call. The data is submitted in the following format:

Request

POST /myapp/callback
Content-Type: application/json

{
    "process" : "myProcess",
    "event" : "END",
    "timestamp" : "2018-07-24T08:53:55.622+02:00",
    "variables" : {
        "variable_1" : "value"
    },
    "_links": {
        "instance": {
            "href": "/process/instances/myInstance"
        }
    }
}

Meaning of fields

  • process: The identifier of the process.
  • event: The event. Contains the value END for successful completion and the value CANCELLED in case of manual cancellation.
  • timestamp: Time of the event (in RFC3339 format).
  • variables: Variables at the time of the end. Not sent in case of manual cancellation. For more information on the format, see section Basic information about process variables.
  • links: Links. The link relation instance indicates the associated process instance (not available in single-use processes).

warning: If an error occurs during the conversion of the variables, the affected variable is not submitted with the callback. Examples of potential causes of an error are inconsistencies between the data type and the actual value.

The **incidentCallback ** URI is called within the process instance with the HTTP POST request each time an error occurs that is visible in monitoring. If the target address follows the base address, the call is authenticated.

The process app uses the app user "process@app.idp.d-velop.local" for the call. The data is submitted in the following format:

Request

POST /myapp/incidentCallback
Content-Type: application/json

{
    "process" : "myProcess",
    "event" : "INCIDENT",
    "timestamp" : "2018-07-24T08:53:55.622+02:00",
    "reason" : "The reason for the incident",
    "_links": {
        "instance": {
            "href": "/process/instances/myInstance"
        }
    }
}

Meaning of fields

  • process: The identifier of the process.
  • event: The event. Contains the value INCIDENT.
  • timestamp: Time of the event (in RFC3339 format).
  • reason: The reason for the error.
  • links: Links. The link relation instance indicates the associated process instance (not available in single-use processes).

Returned values for the request

  • 201: The process has been scheduled for the start. The process instance URI is in the Location header.
  • 400: The request is invalid. Maybe the correlation key was already used for another but not identical process start.
  • 401: The user is not logged in.
  • 403: The user is not authorized to start processes.
  • 404: There is no process definition available for the process key.
  • 405: Starting single-use processes using the API is not permitted.
  • 429: Too many requests arrived at the same time (particularly during an anonymous process start). In this case, try again later.

Cancelling process instances

You can use this HTTP interface to cancel a process instance. The use of this interface requires authentication. The authentication must be performed with a user in the role Process administrator.

Use the following request to cancel a process:

Request

POST {Location der Instanz}/cancel
Content-Type: application/json

{
    "cancelReason" : "The process instance is not needed anymore"
}

You have already received the process instance location in the Location header upon starting.

Notes on the content

  • cancelReason: The reason for cancelling the process instance (max. 280 characters).

Returned values for the request

  • 200: The process instance was cancelled.
  • 400: The request is invalid. Maybe you have specified an empty reason or a reason which is too long.
  • 401: The user is not logged in.
  • 403: The user is not authorized to cancel the process instance.
  • 404: There is no process instance with this ID.
  • 409: The request to cancel was sent at a point in time when cancelling is not possible. Cancelling is not possible e.g. when starting or ending the process instance. You can repeat the request later.
  • 410: The request to cancel was sent at a point in time when the process instance was already ended. In this case you do not need to repeat the request.

Search for process instances

You can use this HTTP interface to search for process instances. The use of this interface requires authentication. Perform authentication with a user in the role Process editor or Process administrator.

POST /process/api/instances/search 
Content-Type: application/json

{
  "orderBy" : "businessKey",
  "orderDirection" : "ASC",
  "pageSize" : 50,
  "includeResultVariables" : true,
  "filter" : {
      "processInstanceId" : ["57fe1461-cc54-45fa-903a-a72f19e24c0c"],
      "processName" : ["My process"],
      "processId" : ["myProcess"],
      "processSource" : ["someProcessSource"],
      "processVersion": [1],
      "startTime" : ["[2024-03-01T00:00:00Z..2024-04-01T00:00:00Z]"],
      "endTime" : ["[2024-04-01T00:00:00Z..2024-05-01T00:00:00Z]"],
      "state" : ["ENDED"],
      "businessKey" : ["businessKey"],
      "variables" : {
          "myVariable": ["myVariableValue"],
          "myOtherVariable": ["anotherValue"]
          ...
      },
      "dmsReference": [{
          "repoId": "yourDmsRepositoryId",
          "objectId": "yourDmsObjectId"
      }],
      "correlationKey" : ["correlationKey"],
  }
}

Notes on the content

You can specify a range search with date values as follows, for example:

(2024-01-02T00:00:00Z..2025-01-02T12:00:00Z)
KeyDescriptionDefault valueRestriction
pageSizeNumber of tasks per page in the result.10Range of 1 to 100.
orderByValue by which the result is to be sorted.startTimePermitted values: startTime, endTime and businessKey.
orderDirectionSpecification for the sorting order.ASCPermitted values: ASC for sorting in ascending order and DESC for sorting in descending order.
includeResultVariablesResults include process variables.falseThe parameter affects the duration of the query.
filter.processInstanceIdSearch for process instances based on the ID.-Maximum of 1,000 IDs. Each has a minimum of 1 and maximum of 255 characters.
filter.processNameSearch for process name.-Maximum of one value. Each value has a minimum of 1 and maximum of 255 characters.
filter.processIdSearch for process ID.-Maximum of one value. Each value has a minimum of 1 and maximum of 255 characters.
filter.processSourceSearch for process source.-Maximum of one value. Each value has a minimum of 1 and maximum of 255 characters.
filter.processVersionSearch for process version.-Maximum of one value. Integer.
filter.startTimeSearch for start date.-Maximum of one value. Date entry in accordance with RFC3339. Can only be searched as a range.
filter.endTimeSearch for end date.-Maximum of one value. Date entry in accordance with RFC3339. Can only be searched as a range.
filter.stateSearch for instance status.-Maximum of one value. Permitted values: STARTED, ERROR, CANCELLED, ENDED.
filter.businessKeySearch for business key.-Maximum of one value. Each value has a minimum of 1 and maximum of 255 characters.
filter.correlationKeySearch for correlation key.-Maximum of one value. Each value has a minimum of 1 and maximum of 255 characters.
filter.variablesSearch for process variables.-Maximum of 1,000 variables. You cannot search for variables of the type Object or File or multi-values. In addition, you cannot search for variables of completed or incorrectly started process instances.
filter.variables.xxxSearch entry for a process variable.-Enter exactly one value. The value contains either a number or a string with a minimum of 1 and maximum of 2,000 characters. The key contains a minimum of 1 and a maximum of 255 characters. If you enter a list without values, this filter is ignored.
filter.dmsReferenceSearch for document link.-Enter exactly one value. Search for document links that were created via the dv_attachment variable. Process instances that are faulty directly during the start process are not included.
filter.dmsReference.repoIdID of the DMS repository for the document link being searched.-Enter exactly one value.
filter.dmsReference.objectIdID of the DMS object for the document link being searched.-Enter exactly one value.

For technical reasons, there is an upper limit in the number of values when combining all the filter values. If this number is exceeded, you receive error code 400 with a prompt to reduce the number of parameters. In addition, you cannot filter by the Identity, dmsObject or URL variables if these variables were created before the release of this API.

If you do not specify a processId in the filter, all the processes for which you have authorization are filtered automatically. In this case, note that each process for which you have authorization is counted as a search parameter.

Response

{
  "instances" : [
      {
          "processInstanceId" : "57fe1461-cc54-45fa-903a-a72f19e24c0c",
          "processName" : "My process",
          "processId" : "myProcess",
          "processSource" : "someProcessSource",
          "processVersion": 1,
          "startTime" : "2020-04-23T15:17:09.974+02:00",
          "endTime" : "2020-04-25T15:17:09.974+02:00",
          "state" : "ENDED",
          "businessKey" : "businessKey",
          "variables" : {
              "dv_initiator": "identity:///identityprovider/scim/users/07a71ecc-dc1e-5cab-b339-940fh88a88b8-initiator",
              "dv_sender": "identity:///identityprovider/scim/users/02a71ebc-oe1e-2hab-b736-453ha87a48k8-sender"
              ...
          },
          "correlationKey" : "correlationKey",
          "_links" : {
              "self" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c" },
              "protocol" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c/protocol" },
              "monitoring" : { "href": "/process/monitoring/i/57fe1461-cc54-45fa-903a-a72f19e24c0c" }
          }
      }
      ...
  ],
  "_links": {
    "next": "<optional uri for next page>"
  }
}

Notes on the properties

  • state:
    • STARTED: Instance is running.
    • ERROR: Instance is in an error state.
    • CANCELLED: Instance was cancelled.
    • ENDED: Instance was ended.

Notes on the links

  • next: This link relation is provided if the number of results exceeds the current pageSize. You can use this link to retrieve additional results. Execute the request with identical content.

The HTML links included in the responses are not stable in the long term.

Returned values for the request

  • 200: The information about a process instance was retrieved successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to search for process instances.
  • 406: An incorrect type was transferred in the Accept header.
  • 429: The request was rejected because it has been performed more frequently than permitted.
  • 500: An internal error has occurred during processing the request.

Note on the error response

Possible types of error response:

TypeDescription
tag:process:PARequestValidationExceptionThe sent request is incorrect.

Retrieving information about a process instance

The use of this interface requires authentication. Perform authentication with a user in the role Process editor or Process administrator. A user who only has the Process editor role also requires specific editing rights for the process.

Request

GET /process/api/instances/{processInstanceId}
Content-Type: application/hal+json

The placeholder {processInstanceId} is the ID of the process instance. Alternatively, you can use the URI that you received in the location header when starting the process instance.

Response

{
    "processInstanceId" : "57fe1461-cc54-45fa-903a-a72f19e24c0c",
    "processName" : "My process",
    "processId" : "myProcess",
    "processSource" : "someProcessSource",
    "processVersion": 1,
    "startTime" : "2020-04-23T15:17:09.974+02:00",
    "endTime" : "2020-04-25T15:17:09.974+02:00",
    "state" : "STARTED",
    "businessKey" : "businessKey",
    "variables" : {
        "dv_initiator": "identity:///identityprovider/scim/users/07a71ecc-dc1e-5cab-b339-940fh88a88b8-initiator",
        "dv_sender": "identity:///identityprovider/scim/users/02a71ebc-oe1e-2hab-b736-453ha87a48k8-sender"
        ...
    },
    "tokens" : [
        {
            "activity": {
                "id": "myActivity",
                "name": "My activity",
                "type": "USER"
            },
            "task": {
                "location": "/task/tasks/myTaskId"
            },
            "events": [
                {
                  "type": "timer",
                  "id": "timerForMyActivity",
                  "name": "Timer for 'My activity'",
                  "time": "2024-05-22T15:07:34.000+02:00"
                }   
            ],
            "created": "2020-04-23T15:17:10.009+02:00"
        }
        ...
    ]
    "correlationKey" : "correlationKey",
    "_links" : {
        "self" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c" },
        "diagram" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c/diagram" },
        "protocol" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c/protocol" },
        "monitoring" : { "href": "/process/monitoring/i/57fe1461-cc54-45fa-903a-a72f19e24c0c" },
        "tokens" : { "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c/userTaskTokens" }
    }
}

For running process instances, the tokens field includes only user tasks with corresponding interim timer results. It total, only the first ten tokens are displayed. You can call a full overview of the tokens using the tokens link relation.

If the process instance was ended, the variables field contains the last state of the process variables. If the process instance was cancelled, the response also contains additional information about the cancellation:

{
  ...
  "additionalInformation" : {
      "cancelUserId": "someUserId",
      "cancelReason": "Process had to be cancelled" 
  }
  ...  
}

Notes on the properties

  • state:
    • STARTED: Instance is running.
    • ERROR: Instance is in an error state.
    • CANCELLED: Instance was cancelled.
    • ENDED: Instance was ended.

Note on an activity

  • type: Currently, only the USER type is supported.

Notes on an event

  • time: Time of the event (in RFC3339 format).
  • type: Currently, only the Timer type is supported.

Notes on the links

  • tokens: This link relation is provided when the number of tokens is more than ten. You can use this link relation to display all the tokens.

The HTML links included in the responses are not stable in the long term.

Returned values for the request

  • 200: The information about a process instance was retrieved successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to retrieve a process instance.
  • 406: An incorrect type was transferred in the Accept header.
  • 409: The state of the instance has changed during the request and could not be synchronized. Repeat the request.
  • 429: The request was rejected because it has been performed more frequently than permitted.
  • 500: An internal error has occurred during processing the request.

Retrieve files for a running process instance

You can use this HTTP interface to retrieve file content for a running process instance. The use of this interface requires authentication. Perform authentication with a user in the role Process editor or Process administrator. A user who only has the Process editor role also requires specific editing rights for the process.

Request

GET /process/api/instances/{processInstanceId}/file/{variableName}[/{index}]
Accept: Erwarteter Media-Type der angefragten Datei (optional)

The placeholder {processInstanceId} is the ID of the process instance. The placeholder {variableName} is the name of the “File”-type variable. The placeholder {index} is the zero-based index of the specific file when using a “File”-type variable with multi-values.

Response

<Your file data>

Returned values for the request

  • 200: The data from the file was retrieved successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to retrieve the file content.
  • 404: The process instance is unavailable or no “File”-type variable with this name or index exists.
  • 406: An incorrect type was transferred in the Accept header.
  • 429: The request was rejected because it has been performed more frequently than permitted.
  • 500: An internal error has occurred during processing the request.

Search for active process tokens

You can use this HTTP interface to search for active process tokens. The use of this interface requires authentication. Perform authentication with a user in the role Process editor or Process administrator.

POST /process/api/tokens/search 
Content-Type: application/json

{
  "orderDirection" : "ASC",
  "pageSize" : 10,
  "filter" : {
      "processInstanceId" : ["57fe1461-cc54-45fa-903a-a72f19e24c0c"],
      "processId" : ["myProcess"],
      "processVersion": [1],
      "activityId" : ["Activity_1vmwv8a"]
  }
}

Notes on the content

For the search, you must always specify either a processId or a processInstanceId. Currently, sorting is performed only by start date (created property).

KeyDescriptionDefault valueRestriction
pageSizeNumber of tokens per page in the result.10Maximum of 100.
orderDirectionSpecification for the sorting order.ASCPermitted values: ASC for sorting in ascending order and DESC for sorting in descending order.
filter.processInstanceIdSearch for process instance ID.-Maximum of 255 characters. Maximum of one ID.
filter.processIdSearch for process ID.-Maximum of 255 characters. Maximum of one ID.
filter.processVersionSearch for process version.-Maximum of one version. Integer.
filter.activityIdSearch for token activity ID.-Maximum of 255 characters. Maximum of one ID.

If you do not specify a processId in the filter, all the processes for which you have authorization are filtered automatically.

Response

{
    "tokens": [
        {
            "processInstanceId": "57fe1461-cc54-45fa-903a-a72f19e24c0c",
            "processId": "myProcess",
            "processVersion": 1,
            "activity": {
                "id": "Activity_1vmwv8a",
                "name": "Meine Aufgabe",
                "type": "USER"
            },
            "task" : {
                "location" : "/task/tasks/5tj999718qsp2cj53v1fo2h0ic"
            },
            "events" : [
               {
                  "type" : "timer",
                  "id" : "BoundaryEvent_0sbdyj",
                  "name" : "Timer",
                  "time" : "2024-04-24T12:14:10.068+02:00"
               }
            ],
            "created": "2024-04-23T15:17:10.068+02:00",
            "_links": {
                "self": {
                    "href": "/process/instances/57fe1461-cc54-45fa-903a-a72f19e24c0c/tokens/Activity_1vmwv8a%3Aca6aac3a-0173-11ef-b01c-3448ed9f748d"
                },
                "monitoring": {
                    "href": "/process/monitoring/i/57fe1461-cc54-45fa-903a-a72f19e24c0c/t/Activity_1vmwv8a%3Aca6aac3a-0173-11ef-b01c-3448ed9f748d"
                }
            }
        },
        ...
    ],
    "links": {
      "next": "<optional uri for next page>"
    }
}

Notes on the response

For running process instances, the tokens field includes only user tasks with corresponding interim timer results.

Note on an activity

  • type: Currently, only the USER type is supported.

Note on an event

  • time: Time of the event (in RFC3339 format).
  • type: Currently, only the Timer type is supported.

Note on the links

  • next: This link is used for paging. If you want to query another value range, you must send the same body to this link.

The HTML links included in the responses are not stable in the long term.

Note on the error response

Possible types of error response:

TypeDescription
tag:process:PARequestValidationExceptionThe sent request is incorrect.

Returned values for the request

  • 200: The tokens were retrieved successfully.
  • 401: The user has not been authenticated.
  • 403: The user is not authorized to search for tokens.
  • 406: An incorrect type was transferred in the Accept header.
  • 429: The request was rejected because it has been performed more frequently than permitted.
  • 500: An internal error has occurred during processing the request.

Connecting external services

You will find out in this chapter how you can connect external services to the process app.

Creating an external service

When the process reaches a send task, the endpoint of the specified external service is actively addressed by the process app. Depending on selection, the service can process the request synchronously or asynchronously at a later time.

The request is run by the process app in the name of the system user.

The following data is submitted:

Request

POST /myapp/service
Content-Type: application/json

{
    "input" : {
        "variable_1": ["value 1", "value 2"],
        "variable_2": "value",
        "variable_3": 42.0,
        "variable_4": ["identity:///identityprovider/scim/users/someUserIDPId",
                       "identity:///identityprovider/scim/groups/someGroupIDPId"],
        "variable_5": {
            "id" : "2s2phfclrgkodfjk8hbgp8l7hv",
            "md5Hash" : "970F4AEE88660D712209CB4B57954808",
            "fileSize" : 22,
            "mediaType" : "text/plain"
        }
    },
    "_links" : {
        "success" : { "href" : "/process/custom/response/1232354/success" },
        "fail" : { "href" : "/process/custom/response/1232354/fail" },
        "bpmnerror" : { "href" : "/process/custom/response/1232354/bpmnerror" },
        "singleFileContent": { "href" : "/process/custom/response/1232354/file/{name}", "templated" : true },
        "multiFileContent": { "href" : "/process/custom/response/1232354/file/{name}/{index}", "templated" : true }
    }
}

Meaning of fields

The process waits no more than five seconds for a response. If the service cannot ensure a response in this time slot, the service should adopt the concept of asynchronous response in general.

Synchronous response

A synchronous service can respond to the request in three different ways:

  • Success
  • BPMN error
  • Technical error

Response on success

The synchronous service can respond to the request with status code 200 and the following body to inform the process app that the request has been processed successfully:

Response

Content-Type: application/json

{
    "output" : {
        "variable_1": ["value 1", "value 2"],
        "variable_2": "value",
        "variable_3": 42.0,
        "variable_4": ["identity:///identityprovider/scim/users/someUserIDPId",
    "identity:///identityprovider/scim/groups/someGroupIDPId"]
    }
}

The field output contains the output values of the service.

File-type variables must be read and changed before this request using the interfaces specified in singleFileContent or multiFileContent (see See Special characteristics of “File”-type process variables).

Response on a BPMN error

If the external service should transmit a BPMN error to the process app, the service can respond with status code 200 and the following body:

Response

Content-Type: application/json

{
    "bpmnError": "4711",
    "bpmnErrorMessage": "Some optional message to explain the bpmn error"
}

Response on a technical error

If a technical error occurs during processing the request, the external service can respond with the following HTTP status codes:

  • 400: The request is invalid and could not be processed by the external service. The process app will not attempt any retries. Use this status code if an error occurs already during validation of the import parameters.
  • 401: The authentication is invalid. The process app will not attempt any retries.
  • 403: The process app is not authorized to call this service. The process app will not attempt any retries.
  • 404: The service is unavailable. The process app will retry later on.
  • 405: The service does not support this service. The process app will not attempt any retries.
  • 406: The service cannot deliver the relevant media type. The process app will not attempt any retries.
  • 415: The service cannot process the media type. The process app will not attempt any retries.
  • 500: An internal error has occurred during processing the request. The process app will retry later on. Use this status code if an error occurs during processing.

An error message can be transmitted in the response body optionally:

Response

Content-Type: application/json

{
    "error" : "Error reason"
}

Asynchronous response

An asynchronous service first only confirms the acceptance of the request without processing it directly. For confirmation, the service can respond with status codes 200 or 202 without a body. If the request cannot be received, the service can submit the following error codes:

  • 400: The request is invalid and could not be processed by the external service. The process app will not attempt any retries. Use this status code if an error occurs already during validation of the import parameters.
  • 401: The authentication is invalid. The process app will not attempt any retries.
  • 403: The process app is not authorized to call this service. The process app will not attempt any retries.
  • 404: The service is unavailable. The process app will retry later on.
  • 405: The service does not support this service. The process app will not attempt any retries.
  • 406: The service cannot deliver the relevant media type. The process app will not attempt any retries.
  • 415: The service cannot process the media type. The process app will not attempt any retries.
  • 500: An internal error has occurred during processing the request. The process app will retry later on. Use this status code if an error occurs during processing.

An error message can be transmitted in the response body optionally:

Response

Content-Type: application/json

{
    "error" : "Error reason"
}

If the request was accepted successfully, the service can call one of the links success, bpmnerror or fail at a later time using the HTTP request POST to report success, a BPMN error or a technical error. No authentication by the identity provider app is required for this. The body of the asynchronous response equals the body of the corresponding synchronous response, depending on the response type.

The process app responses with one of the following status codes:

  • 200: The response is valid and the process is continued.
  • 400: The response is invalid (e.g. because invalid variables have been transferred).
  • 409: The process is currently not in a status in which the response can be processed. In this case, the response needs to be tried again at a later time. The process may have been interrupted due to an error.
  • 500: An internal error has occurred.

A special path can be modeled for a BPMN error in the process model. In case of a technical error, an error state is create in the process. Administrators can use this error state to run the service call again.

Resilience of asynchronous services

An asynchronous external service should be resilient. It is possible that the endpoint of the process app is unavailable at the time of the call. If this is the case, the external service receives a response with the status code 404 or 503. If the endpoint of the process app is unavailable at the time of the call, the response needs to be sent again at a later time.

Basic information about process variables

The following functions use process variables:

  • Starting processes
  • Starting single-use processes
  • Notification at process completion
  • Reading, changing and adding process variables to a user task

The process variables are transmitted in the same format for all these functions.

Prerequisite in the process definition

Variable definitions: All variables you want to use need to be defined in BPMN first. You can look up how to define the variables in the documentation of the process app.

Input mapping: If a process variable is to be accessed from a user activity, you need to add an input mapping for these variables in the process definition. If no mapping is done, these variables may be unavailable.

Output mapping: If a user activity is to change or create process variables, you need to define an output mapping for this purpose. Only then will they be available during the further course of the process.

Format of process variables

The process variables are generally transferred in a JSON object. One name-value pair per process variable is transmitted in this object. In the process, each key stands for the name of the process variable from the process definition.

Example

{
    "variable_1" : "some value",
    "variable_2" : ["multiple", "values"],
    "variable_3" : {
      "myKey" : "myValue"
    }
}

Process variables are transmitted differently via JSON depending on type. These rules apply to the existing data types:

FileTransmission asExample
StringJSON string"Hello"
NumberJSON number47.11
BooleanJSON booleantrue
IdentityJSON string in this format:
identity://{uri}		"identity:///identityprovider/scim/users/johnsmith"
DmsObjectJSON string in this format:
dmsObject://{uri}		"dmsObject:///dms/r/123/o2/xyz"
URLJSON string in a valid URL format according to RFC 2396:"https://www.d-velop.de"
ObjectJSON object{"myKey" : "myValue"}
FileJSON object with a specific structure; see Special characteristics of “File”-type process variables

Removing a variable

To delete a value for a writing API function, you can transfer the value null. This variable will no longer appear in subsequent readings.

{
"variable_1" : null
}

Multi-values

Multi-values are displayed as JSON arrays. These must contain at least one value of the associated data type. Zero values are only permitted if the array contains at least one valid value. Values of another data type are not permitted in multi-values.

Example for multi-values

["dog", "cat", "horse"]

Mandatory variables

Variables defined as mandatory variables cannot be deleted once the have been written. In addition, mandatory variables of data type String may not contain an empty string.

These rules additionally apply to mandatory variables for external services:

  • Input variables: If an input variable does not exist or is empty, an error is created in the process and the service is not called.
  • Output variables: If the service call does not specify a mandatory variable in the response, an error is created in the process.

Validation

During the transfer of process variables, all transferred data is validated against the process definition. If the validation fails, the response includes the status code 400.

The acceptance will be denied in the following situations:

  • No definition exists for a transferred variable.
  • The transferred data type deviates from the definition.
  • A mandatory variable is to be deleted.
  • Variable values are too long. A variable of the type String must not be longer than 500 characters. In case of multi-values, this applies to each individual value.

Special characteristics of “File”-type process variables

Due to their potential size, File-type process variables are usually not transferred in the same request when reading and writing process variables. Instead, two predefined links are returned while reading. You can use these links to read and write the files in separate requests:

{
  "_links": {
    singleFileContent": {
      "href": "/process/.../file/{name}",
      "templated": true
    },
    "multiFileContent": {
      "href": "/process/.../file/{name}/{index}",
      "templated": true
    }
  }
}
  • singleFileContent: You can use this interface to read (GET) or change (PUT) File-type content (single value). Replace with the name of the variables.
    • GET: Accept: {media type of the file}
    • PUT: Content-Type: {media type of the file}
  • multiFileContent: You can use this interface to read (GET), add (POST) or change (PUT) File-type content (multi-value). Replace with the name of the variables and replace with the index.
    • GET: Accept: {media type of the file}
    • PUT: Content-Type: {media type of the file}
    • POST: Content-Type: {media type of the file}

Since requests to the singleFileContent and multiFileContent links may take a long time depending on the size of the file, only a limited number of parallel requests to these links is permitted. Other requests are rejected with status code 429. In this case, try again later.

For specific interfaces and only up to an overall size of 10 MB across all the files sent, a direct transfer together with the other process variables is also possible. The File-type variables are transferred as Base64 values in the following JSON object:

{
    "mediaType" : "text/plain",
    "base64value" : "RmlsZSBjb250ZW50IGFzIGJhc2U2NA=="
}

In all other cases, only references are transferred to the files. The following JSON object is used:

{
    "id" : "2s2phfclrgkodfjk8hbgp8l7hv",
    "md5Hash" : "970F4AEE88660D712209CB4B57954808",
    "fileSize" : 22,
    "mediaType" : "text/plain"
}

File references make it easy to swap values in a multi-value, for example, or to use the same file for multiple process variables.

To create a new file reference, you can use createNew:

{
    "createNew" : true
}

Meaning of fields

  • base64value: Content of the file in Base64 encoding.
  • id: Unique ID of the file reference.
  • md5Hash: MD5 hash of the file.
  • fileSize: Size of the file in bytes.
  • mediaType: Media type of the file.
  • createNew: Specifies that a new file reference is to be created.

The following interfaces use Base64 values and file references:

  • Process start: Base64 values
  • User activities: File references. Exception: The parameter streamFileValues=true is appended.
  • External services: File references

Accessing process variables in a user activity

You can use this HTTP interface to access process variables. Access is possible only if a process is part of a user activity and process instance is currently exactly at this step.

The URI of this resource needs to be dynamically determined using the expression ${process.task.variablesUri} for the "form key" of an edit form. You can find more detailed information on this in the documentation of the process app.

This function can be used to access the process variables in a user interface. The use of this interface requires authentication with the identity provider app.

Use the following request for access to process variables:

Request

GET /${process.task.variablesUri}
Accept: application/hal+json

Response

{
    "variables": {
        "variable_1" : ["value 1", "value 2"],
        "variable_2" : "value",
        "variable_3": 42.0,
        "variable_4": ["identity:///identityprovider/scim/users/someUserIDPId",
                       "identity:///identityprovider/scim/groups/someGroupIDPId"],
        "variable_5": {
            "id" : "2s2phfclrgkodfjk8hbgp8l7hv",
            "md5Hash" : "970F4AEE88660D712209CB4B57954808",
            "fileSize" : 22,
            "mediaType" : "text/plain"
        }
    },
    "_links": {
        "singleFileContent": { "href" : "${process.task.variablesUri}/file/{name}", "templated" : true },
        "multiFileContent": { "href" : "${process.task.variablesUri}/file/{name}/{index}", "templated" : true }
    }
}

The field variables contains the process variables. For more information on the format, see section Basic information about process variables.

If you want to query the Base64 values of the file variables directly in a user activity instead of the file references, you can append the parameter streamFileValues=true. The links are then not returned:

Request

GET /${process.task.variablesUri}?streamFileValues=true
Accept: application/hal+json

Response

{
    "variables": {
        "variable_1" : ["value 1", "value 2"],
        "variable_2" : "value",
        "variable_3": 42.0,
        "variable_4": ["identity:///identityprovider/scim/users/someUserIDPId",
                       "identity:///identityprovider/scim/groups/someGroupIDPId"],
        "variable_5": {
            "base64value" : "SGVsbG8gd29ybGQh",
            "mediaType" : "text/plain"
        }
    }
}

If an error occurs during the conversion of the variables, the affected variable is not submitted with the response. An example of a potential error is an inconsistency between the data type and the actual value.

info: Only the user who currently has the user activity open is allowed to query the variables.

Returned values for the request

  • 200: The variables were returned successfully.
  • 400: The answer is invalid.
  • 401: No valid authentication was transferred.
  • 403: The user is not authorized to query the variables.
  • 404: The entered task no longer exists.
  • 409: The entered task has not been successfully delivered to the user (task app) yet or the process was interrupted due to an error.

Changing or adding process variables from a user step

You can use this function to change a part of the process variables.

Request

PUT /${process.task.variablesUri}
Content-Type: application/json

{
    "variables" : {
        "variable_1" : ["value 1", "value 2"],
        "variable_2" : "value",
        "variable_3": 42.0,
        "variable_4": ["identity:///identityprovider/scim/users/someUserIDPId",
                       "identity:///identityprovider/scim/groups/someGroupIDPId"],
        "variable_5": {
            "myKey" : "myValue"
        },
        "dv_decision" : "Granted",
        "dv_comment" : "I approve"
    }
}

info: Only the current user of the user activity is allowed to change the variables.

Returned values for the request

  • 200: The variables were changed successfully.
  • 400: The request is invalid.
  • 401: No valid authentication was transferred.
  • 403: The user is not authorized to change the variables.
  • 404: The entered task no longer exists.
  • 409: The process is currently in a status in which variables cannot be changed. The process may have been interrupted due to an error.

Triggering a process event

Using this function you can trigger a process event. You can determine the URI in the process administration.

Request

POST Endpunkt-URI
Content-Type: application/json
Content-Length: XXX

{ 
  ...
}

The endpoint can accept any JSON. Using the mapping in the endpoint configuration, you determine which properties are used in the process event.

You have to submit the Content-Length header in any case. The content must not exceed 100 KB in size.

Returned values for the request

  • 202: The event was received.
  • 204: The event has not been completely configured yet.
  • 400: The request is invalid.
  • 401: No valid authentication was transferred.
  • 404: The endpoint does not exist.
  • 415: The content type is not supported.