This article describes the Identity Manager Process REST API which can be used to control processes in Smart ID Identity Manager.

This article includes updates for Smart ID 23.04.

The API provides a simple RESTful interface for starting and proceeding processes and for exchanging data with it. The Identity Manager Process REST API is part of the Identity Manager main application and will be available automatically after starting the server that hosts the application.

Use the Identity Manager Process REST API

See the following topics for more information on how to use the Identity Manager Process REST API:

The REST API is secured by default. Therefore it is not possible for intruders to access data and functionality of the REST interface. The default configuration uses our internal authentication profile to authenticate the user and to perform the authorization.

By default, the HTTP Basic Authentication is used. The client calling our service is responsible to fill the Authorization Header of the HTTP request.

Never use the HTTP Basic Authentication without securing the communication channel using SSL, so make sure you access the server using HTTPS.

To configure the authentication process and the security settings, see the Spring Security filter settings in the security-beans.xml.

The root context is the base context for all webservice requests. Specific requests must construct a path consisting of this base context plus the specific functionality.

context	URL
root context with https	[root_context] = https://[host]:[port]/[application_name]/ws
process interface	[root_context]/processes/
task interface	[root_context]/tasks/
tenant selection

Depending on the configuration of your server and authorization mechanism, the protocol can be HTTP or HTTPS. For more information, see the previous section.

Make sure you specify the right port for your application server.

To select the tenant id, append the tenant id to the URL, that is, the primary key of the tenant in the database:

[URL]?tenantId=xxx

Example: Start process with tenant selection

http://myServer:8080/idm-operator/ws/processes/MyProcess/start?tenantId=1234

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.

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_.

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.

Available commands

Start process

Description

Starts the process defined by processDefinitionKey.

URL

[root_context]/processes/{processDefinitionKey}/start?tenantId=xxx

where processDefinitionKey is the ID of the BPMN process.

Method

POST

Content type

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

Request parameters

Multiple Request Parameters can be concatenated with "&"

Parameter	Description	Required or Optional
?searchConfigName=myName	This query parameter identifies the search configuration for searching for one core object.	Optional
?tenantId=myTenant	This query parameter identifies the tenant for which the process should be started. This information is also used to authenticate the user (depending on the authorization mechanism).	Required
?requiredUserTask=myTask	This query parameter identifies a user task task has to be present in the given top-level process for the process to be started.	Optional

Body

The request body can be used to fill the data map for the process which shall be started. The form should be like:

<data>
	<field name="BaseDpEmployee_FirstName">Max</field>
	<field name="BaseDpEmployee_LastName" type="STRING">Muster</field> 
	<field name="BaseDbEmployee_Photo" type="BYTES">{base64EncodedPhoto}</field>
	<field name="BaseDbEmployee_BirthDate" type="DATE">2001-10-25T00:00:00+02:00</field> 
</data>

Response

Possible response codes:

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

Example: Error response with http status code 400

process definition [myProcess] with required user-task [myTask] does not exist

Example: Error response with http status code 500

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>No core template with name "null" was found.</message>
</restError>

Example: Successful response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<process instanceId="4711"/>

Example: Error response with http status code 500 – JSON format

{
    "message": "Process \"\"' not found."
}

Example: Successful response – JSON format

{
    "data": null,
    "instanceId": "4711"
}

Execute 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

[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

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

Possible response codes:

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

Example: Error response with http status code 500

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>No core template with name "null" was found.</message>
</restError>

Example: Successful response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<process instanceId="4711"/>

Example: Error response with HTTP status code 500 – JSON format

{
    "message": "No core template with name \"null\" was found."
}

Example: Successful response – JSON format

{
    "data": null,
    "instanceId": "4711"
}

Obtain task data

Description

Obtains the data map a the start of a task for a given process instance. The process instance is given by the parameter processInstanceId. The task which data has to be obtained is given by the passed taskId.

URL

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

Method

GET

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

Example responses

Example: Successful response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
    <field name="Person_Email">max.muster@nexusgroup.de</field>
    <field name="Person_FirstName">Max</field>
    <field name="Person_Id">5678</field>
    <field name="Person_LastName">Muster</field>
    <field name="Meta_CoreTemplateName_Person">Person</field>
    <field name="Person_PersonnelNumber">123456</field>
</data>

Example: Successful response – JSON format

{
    "field": [
        {
            "value": "max.muster@nexusgroup.de",
            "name": "Person_Email",
            "type": "STRING",
            "valueObject": "max.muster@nexusgroup.de"
        },
        {
            "value": "Max",
            "name": "Person_FirstName",
            "type": "STRING",
            "valueObject": "Max"
        },
        {
            "value": "5678",
            "name": "Person_Id",
            "type": "STRING",
            "valueObject": "5678"
        },

        {
            "value": "Muster",
            "name": "Person_LastName",
            "type": "STRING",
            "valueObject": "Muster"
        },
        {
            "value": "Person",
            "name": "Meta_CoreTemplateName_Person",
            "type": "STRING",
            "valueObject": "Person"
        },
        {
            "value": "123456",
            "name": "Person_PersonnelNumber",
            "type": "STRING",
            "valueObject": "123456"
        }
    ]
}

Start process, poll for data and execute task

Description

This command will start a process. The process is expected to reach a user task without further interaction. Also,the user task is intended merely as a waiting point and must not make any changes. The command will try to fetch the process data before the user task and then execute the user task (like clicking "Next").

URL

[root_context]/processes/{processDefinitionKey}/startGetDataAndExecute/{taskId}?tenantId=xxx

where processDefinitionKey is the ID of the BPMN process and taskId is the ID of the user task at which to get the data and which to execute.

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

Method

POST

Content type

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

Request parameters

Multiple Request Parameters can be concatenated with "&"

Parameter	Description	Required or Optional
?searchConfigName=myName	This query parameter identifies the search configuration for searching for one core object.	Optional
?tenantId=myTenant	This query parameter identifies the tenant for which the process should be started. This information is also used to authenticate the user (depending on the authorization mechanism).	Required
?maxAttempts=10	This query parameter defines how often to poll for data at the given task before giving up. Minimum value: 1	Required
?interval=5000	This query parameter defines the polling interval in msec. Minimum value: 100	Required

Body

The request body can be used to fill the data map for the process which shall be started. The form should be like:

<data>
	<field name="BaseDpEmployee_FirstName">Max</field>
 	<field name="BaseDpEmployee_LastName" type="STRING">Muster</field> 
    <field name="BaseDbEmployee_Photo" type="BYTES">{base64EncodedPhoto}</field>
 	<field name="BaseDbEmployee_BirthDate" type="DATE">2001-10-25T00:00:00+02:00</field>
</data>

Response

Possible response codes:

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

Example: Error response with http status code 400

process definition [myProcess] with user-task [myTask] does not exist

Example: Error response with http status code 400

maxAttempts must be at least 1

Example: Error response with http status code 500

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>All [10] data fetch attempts attempts with interval [5000]msec for task [myTask] of process [myProcessDefinition] failed. Process instance[4711] might be stuck!</message>
</restError>

Example: Error response with http status code 500

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>No core template with name "null" was found.</message>
</restError>

Example: Error response with http status code 500 (data fetched, but task execution failed)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
    <!-- note the additional field "RestError" compared to a successful response -->
	<field name="RestError">some error happened trying to execute the task</field>
    <field name="Person_Email">max.muster@nexusgroup.de</field>
    <field name="Person_FirstName">Max</field>
    <field name="Person_Id">5678</field>
    <field name="Person_LastName">Muster</field>
    <field name="Meta_CoreTemplateName_Person">Person</field>
    <field name="Person_PersonnelNumber">123456</field>
</data>

Example: Successful response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
    <field name="Person_Email">max.muster@nexusgroup.de</field>
    <field name="Person_FirstName">Max</field>
    <field name="Person_Id">5678</field>
    <field name="Person_LastName">Muster</field>
    <field name="Meta_CoreTemplateName_Person">Person</field>
    <field name="Person_PersonnelNumber">123456</field>
</data>

Example: Error response with HTTP status code 400 – JSON format

process definition [myProcess] with user-task [myTask] does not exist

Example: Error response with HTTP status code 400 – JSON format

maxAttempts must be at least 1

Example: Error response with HTTP status code 500 – JSON format

{
    "message": "All [10] data fetch attempts attempts with interval [5000]msec for task [myTask] of process [myProcessDefinition] failed. Process instance[4711] might be stuck!"
}

Example: Error response with HTTP status code 500 – JSON format

{
    "message": "No core template with name \"null\" was found."
}

Example: Error response with HTTP status code 500 (data fetched, but task execution failed) – JSON format

{
    "field": [
        {
            "value": "some error happened trying to execute the task",
            "name": RestError",
            "type": "STRING",
            "valueObject": "some error happened trying to execute the task"
        },
        {
            "value": "max.muster@nexusgroup.de",
            "name": "Person_Email",
            "type": "STRING",
            "valueObject": "max.muster@nexusgroup.de"
        },
        {
            "value": "Max",
            "name": "Person_FirstName",
            "type": "STRING",
            "valueObject": "Max"
        },
        {
            "value": "5678",
            "name": "Person_Id",
            "type": "STRING",
            "valueObject": "5678"
        },

        {
            "value": "Muster",
            "name": "Person_LastName",
            "type": "STRING",
            "valueObject": "Muster"
        },
        {
            "value": "Person",
            "name": "Meta_CoreTemplateName_Person",
            "type": "STRING",
            "valueObject": "Person"
        },
        {
            "value": "123456",
            "name": "Person_PersonnelNumber",
            "type": "STRING",
            "valueObject": "123456"
        }
    ]
}

Example: Successful response – JSON format

{
    "field": [
        {
            "value": "max.muster@nexusgroup.de",
            "name": "Person_Email",
            "type": "STRING",
            "valueObject": "max.muster@nexusgroup.de"
        },
        {
            "value": "Max",
            "name": "Person_FirstName",
            "type": "STRING",
            "valueObject": "Max"
        },
        {
            "value": "5678",
            "name": "Person_Id",
            "type": "STRING",
            "valueObject": "5678"
        },

        {
            "value": "Muster",
            "name": "Person_LastName",
            "type": "STRING",
            "valueObject": "Muster"
        },
        {
            "value": "Person",
            "name": "Meta_CoreTemplateName_Person",
            "type": "STRING",
            "valueObject": "Person"
        },
        {
            "value": "123456",
            "name": "Person_PersonnelNumber",
            "type": "STRING",
            "valueObject": "123456"
        }
    ]
}

Obtain task data and execute task if data available

Description

Obtains the data map at the start of a task for a given process instance. If data could be obtained, the task will then be executed (like clicking "Next"). The process instance is given by the parameter processInstanceId. The task which data has to be obtained is given by the passed taskId.

URL

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

Method

POST

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

If no data is available, you get the following status code:

Status Code	Description
204	No Content

Possible response codes:

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

Example: Error response with http status code 400

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>Task with id '[myTask]' not found for process with id '[instanceId]'.</message>
</restError>

Example: Error response with http status code 500 (data fetched, but task execution failed)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
    <!-- note the additional field "RestError" compared to a successful response -->
	<field name="RestError>some error happened trying to execute the task</field>
    <field name="Person_Email">max.muster@nexusgroup.de</field>
    <field name="Person_FirstName">Max</field>
    <field name="Person_Id">5678</field>
    <field name="Person_LastName">Muster</field>
    <field name="Meta_CoreTemplateName_Person">Person</field>
    <field name="Person_PersonnelNumber">123456</field>
</data>

Example: Successful response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
    <field name="Person_Email">max.muster@nexusgroup.de</field>
    <field name="Person_FirstName">Max</field>
    <field name="Person_Id">5678</field>
    <field name="Person_LastName">Muster</field>
    <field name="Meta_CoreTemplateName_Person">Person</field>
    <field name="Person_PersonnelNumber">123456</field>
</data>

Example: Error response with HTTP status code 400 – JSON format

{
    "message": "Task with id '[myTask]' not found for process with id [instanceId]'."
}

Example: Error response with HTTP status code 500 (data fetched, but task execution failed) – JSON format

{
    "field": [
        {
            "value": "some error happened trying to execute the task",
            "name": RestError",
            "type": "STRING",
            "valueObject": "some error happened trying to execute the task"
        },
       {
            "value": "max.muster@nexusgroup.de",
            "name": "Person_Email",
            "type": "STRING",
            "valueObject": "max.muster@nexusgroup.de"
        },
        {
            "value": "Max",
            "name": "Person_FirstName",
            "type": "STRING",
            "valueObject": "Max"
        },
        {
            "value": "5678",
            "name": "Person_Id",
            "type": "STRING",
            "valueObject": "5678"
        },
        {
            "value": "Muster",
            "name": "Person_LastName",
            "type": "STRING",
            "valueObject": "Muster"
        },
        {
            "value": "Person",
            "name": "Meta_CoreTemplateName_Person",
            "type": "STRING",
            "valueObject": "Person"
        },
        {
            "value": "123456",
            "name": "Person_PersonnelNumber",
            "type": "STRING",
            "valueObject": "123456"
        }
    ]
}

Example: Successful response – JSON format

{
    "field": [
       {
            "value": "max.muster@nexusgroup.de",
            "name": "Person_Email",
            "type": "STRING",
            "valueObject": "max.muster@nexusgroup.de"
        },
        {
            "value": "Max",
            "name": "Person_FirstName",
            "type": "STRING",
            "valueObject": "Max"
        },
        {
            "value": "5678",
            "name": "Person_Id",
            "type": "STRING",
            "valueObject": "5678"
        },
        {
            "value": "Muster",
            "name": "Person_LastName",
            "type": "STRING",
            "valueObject": "Muster"
        },
        {
            "value": "Person",
            "name": "Meta_CoreTemplateName_Person",
            "type": "STRING",
            "valueObject": "Person"
        },
        {
            "value": "123456",
            "name": "Person_PersonnelNumber",
            "type": "STRING",
            "valueObject": "123456"
        }
    ]
}

Controlling 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

<?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>

The action variable must be true.

Example: Simulate a click on the Next button (set as default flow)

<?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>

The action variable is not required here.

Example: Simulate a click on the Cancel button

<?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>

The action variable must be false.

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.

Supported field types

There are three possible values for the type attribute of a field:

Type

Default

Description

STRING

For UTF-8 strings.

BYTES

For binary values, given as base64.

When passing CSRs, certificates and the like, always set the pure base64 value.
PEM is not supported.

DATE

For date values, given in the format %Y-%M-%DT%h:%m:%s%z

Example:

2001-10-25T00:00:00+02:00

Space shortcuts

Page tree

Visit Nexus to get an overview of Nexus' solutions, read customer cases, access the latest news, and more.

Identity Manager Process REST API

Use the Identity Manager Process REST API

Available commands

Start process

Description

URL

Method

Content type

Header parameters

Request parameters

Body

Response

Example responses

Execute task

Description

URL

Method

Content type

Header parameters

Response

Example responses

Obtain task data

Description

URL

Method

Header parameters

Example responses

Start process, poll for data and execute task

Description

URL

Method

Content type

Header parameters

Request parameters

Body

Response

Example responses

Obtain task data and execute task if data available

Description

URL

Method

Header parameters

Response

Example responses

Controlling the execution flow of a process

Description

Examples

Supported field types

Example: