Process-App

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 may not be larger than the value of processInstanceRetentionTime (if it is larger 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 transferred configurations 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/{id}/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/{id}/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 for starting a process without authentication.

Replace the placeholder {id} 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).

Important

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 simultaneous requests have been received (especially with an anonymous process start). Try again later in this case.

 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.

 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"]
    },
    "_links" : {
        "success" : { "href" : "/process/custom/response/1232354/success" },
        "fail" : { "href" : "/process/custom/response/1232354/fail" },
        "bpmnerror" : { "href" : "/process/custom/response/1232354/bpmnerror" }
    }
}

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.

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 corresponding 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 corresponding 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 state 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"}

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.

 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"]
    }
}

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

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.

Note

Only the current user of the user activity 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"
    }
}

Note

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 state in which the 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.