Edit on Github

Submit Start Form

Starts a process instance using a set of process variables and the business key. If the start event has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See Documentation on Generated Task Forms.

Method

POST /process-definition/{id}/submit-form

POST /process-definition/key/{key}/submit-form (starts the latest version of the process definition which belongs to no tenant)

POST /process-definition/key/{key}/tenant-id/{tenant-id}/submit-form (starts the latest version of the process definition for tenant)

Parameters

Path Parameters

Name Description
id The id of the process definition to submit the form for.
key The key of the process definition (the latest version thereof) to be retrieved.
tenant-id The id of the tenant the process definition belongs to.

Request Body

A JSON object with the following properties:

Name Description
variables A JSON object containing the variables the process is to be initialized with. Each key corresponds to a variable name and each value to a variable value. A variable value is a JSON object with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.

For variables of type File the value has to be submitted as Base64 encoded string.

type The value type of the variable.
valueInfo A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

For serialized variables of type File, the following properties can be provided:

  • filename: The name of the file. This is not the variable name but the name that will be used when downloading the file again.
  • mimetype: The MIME type of the file that is being uploaded.
  • encoding: The encoding of the file that is being uploaded.

The following property can be provided for all value types:

  • transient: Indicates whether the variable should be transient or not. See documentation for more informations.

business key A JSON object containing the business key the process is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.

Result

A JSON object corresponding to the ProcessInstance interface in the engine. Its properties are as follows:

Name Type Description
id String The id of the process instance.
definitionId String The id of the process definition.
businessKey String The business key of the process instance.
caseInstanceId String The case instance id of the process instance.
tenantId String The tenant id of the process instance.
ended Boolean A flag indicating whether the instance is still running or not.
suspended Boolean A flag indicating whether the instance is suspended or not.
links Object A JSON array containing links to interact with the instance.

Response Codes

Code Media type Description
200 Request successful.
400 application/json The variable value or type is invalid, for example if the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
404 application/json Process definition with given key does not exist. See the Introduction for the error response format.
500 application/json The instance could not be created successfully. See the Introduction for the error response format.

Example

Request

POST /process-definition/aProcessDefinitionId/submit-form

POST /process-definition/key/aProcessDefinitionKey/submit-form

Request Body:

    {
      "variables": {
        "aVariable" : {
          "value" : "aStringValue",
          "type": "String",
          "valueInfo" : {
            "transient" : true
          }
        },
        "anotherVariable" : {
          "value" : true,
          "type": "Boolean"
        }
      },
      "businessKey" : "myBusinessKey"
    }

Response

{
  "links":[
    {
      "method": "GET",
      "href":"http://localhost:8080/rest-test/process-instance/anId",
      "rel":"self"
    }
  ],
  "id": "anId",
  "definitionId": "aProcessDefinitionId",
  "caseInstanceId": null,
  "businessKey": "myBusinessKey",
  "ended": false,
  "suspended": false,
  "tenantId": null
}

On this Page: