Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This article includes updates for Smart ID 23.04.

...

Expand
titleResolve secrets over the REST API

By default, no secrets are resolved when querying for example the data map of a certain process step.

If the user which calls the REST API has the EXECUTION permission api.resolveSecrets, which can be defined in the designer, then secrets are resolved. The field is the same as the one which would contain the UUID of the secretFieldStore, for example Person_PasswordRef.


Expand
titleFind task ID

To run a command on a specific task, you will need a taskId.

To find the taskId, look up the value of the id attribute of the specific process in the BPMN 2.0 process definition, in the file process.xml.

Or, if you rather want to get the information from the database, look into the table ACT_RU_TASK in the column Task_Def_Key_. Don´t use ID_.


Expand
titleControl process flow

Putting variables into the process is possible when starting the process or executing a task by sending an XML snippet to the endpoints respectively. See section "Controlling the execution flow of a process" for more information.

...

true

Possible response codes: 

Expand
titleExecute task

Description

Executes a task for a process instance. The process instance for which the task should be executed is given by the passed processInstanceId. The task to execute is given by the passed task id.

URL

Code Block
[root_context]/tasks/{processInstanceId}/{taskId}?tenantId=xxx

To find the task id, look up the id of the task in the BPMN 2.0 process definition.

Method

POST

Content type

Code Block
application/xml

Header parameters

Parameter

Description

Required or Optional

Authorization

To pass authentication information to the server, we use the HTTP basic authentication. The authorization information is passed as HTTP header parameter in the form username:password Base64 encoded (admin:admin in the following example):

Authorization: Basic YWRtaW46YWRtaW4=

Required

Accept-Language

If the exception which can occur on the server is translatable you can determine the output language of the exception message with this parameter:

Accept-Language: en

Optional

Accept

If the Accept header is not provided, the system is using the default value as “application/xml”.

If you set the header as “application/json”, you will receive a JSON format response.

Accept: application/json

Optional

Response

Insert excerpt
Identity Manager Process REST APIIdentity Manager Process REST APInopanel

Status Code

Description

200

OK

400

Bad Request: see RestError in response body for details

401

Unauthorized: no valid authentication provided

403

Forbidden: the user does not have the permissions to execute/acccess the user task

500 

Internal Server Error: see RestError in response body for details

Example responses

XML format

Example: Error response with http status code 500
Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>No core template with name "null" was found.</message>
</restError>


Example: Successful response
Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<process instanceId="4711"/>


JSON format

Example: Error response with HTTP status code 500 – JSON format
Code Block
languagexml
{
    "message": "No core template with name \"null\" was found."
}


Example: Successful response – JSON format
Code Block
languagexml
{
    "data": null,
    "instanceId": "4711"
}


...

Expand
titleControlling the execution flow of a process

Description

Use the Execute task endpoint of the REST API to complete the user task (open task) and control the flow of the process.

Executing a process via the public REST interface behaves as follows when the process encounters a user task:

  • The process stops and waits for further input

  • The API user must provide the form data as payload of an http request to the exec endpoint

  • The process continues its execution regardless of any button that is associated to the form/user task

  • In order to influence the execution path of the process (for example at gateways), you can also set the values of the flow variables in the payload

Examples

Example: Simulate a click on the Next button
Code Block
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
  <field name="Person_FirstName" type="STRING">Bernhard</field>
  <field name="Person_LastName" type="STRING">Adam</field>
  <field name="action" type="STRING">true</field>
</data>


Note

The action variable must be true.


Example: Simulate a click on the Next button (set as default flow)
Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
  <field name="Person_FirstName" type="STRING">Bernhard</field>
  <field name="Person_LastName" type="STRING">Adam</field>
</data>


Note

The action variable is not required here.


Example: Simulate a click on the Cancel button
Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
  <field name="Person_FirstName" type="STRING">Bernhard</field>
  <field name="Person_LastName" type="STRING">Adam</field>
  <field name="action" type="STRING">false</field>
</data>


Note

The action variable must be false.


Note
  • The first two examples (simulating a click on the NEXT button) are alternatives.

  • As soon as a gateway uses a variable in its condition and there is no flow marked as default, then the variable must be set and send to the endpoint. Otherwise you get an error response.

  • You can not add variables to the 'Obtain task data and execute task' endpoint even though it is POST request. But you may send variables to the process when starting it.

  • The button function CANCEL is not supported. Executing an open user task through the REST API will always continue with the button function NEXT.


...