Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Clarified description in "Start process, poll for data and execute task" and also moved that section

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

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. 

Expandall

How to use the Identity Manager Process REST API

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

Expand
titleSecure REST API calls with HTTPS

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.

Note

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.


Expand
titleSet the root context in the API call

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.

contextURL

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. 


Expand
titleSelect a tenant in the API call

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


Code Block
languagexml
titleExample: Start process with tenant selection
http://myServer:8080/prime_explorer/ws/processes/MyProcess/start?tenantId=1234



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

Available commands

Start process

Expand
titlePOST [root_context]/processes/{processDefinitionKey}/start

Description

Starts the process defined by processDefinitionKey.

URL

Code Block
[root_context]/processes/{processDefinitionKey}/start

where processDefinitionKey is the ID of the BPMN process.

Method

POST

Content Type

Code Block
application/xml


Header Parameters

ParameterDescriptionRequired 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


Request Parameters

Multiple Request Parameters can be concatenated with "&"

ParameterDescriptionRequired or Optional
?searchConfigName=myNameThis 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=myTaskThis 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:

Code Block
languagexml
<data>
	<field name="BaseDpEmployee_FirstName">Max</field>
	<field name="BaseDbEmployee_Photo">{base64EncodedPhoto}</field>
</data>


Response

In case of an Error you'll get the following status codes:

  • 400 - Bad Request
  • 500 - Internal Server error


Example responses

Code Block
titleExample: Error response with http status code 400
process definition [myProcess] with required user-task [myTask] does not exist


Code Block
languagexml
titleExample: 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>


Code Block
languagexml
titleExample: Successful response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<process instanceId="4711"/>
Start process, poll for data and execute


Execute task

Body

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

Expand
titlePOST [root_context]/processestasks/{processDefinitionKeyprocessInstanceId}/startGetDataAndExecute/{taskId}

Description

Starts the process defined by processDefinitionKey, tries for a while to fetch data at user task taskId, then finally executes the task if data could be fetched.

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]/processestasks/{processDefinitionKeyprocessInstanceId}/startGetDataAndExecute/{taskId}
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

Code Block
application/xml

Header Parameters

ParameterDescriptionRequired 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

Request Parameters

Multiple Request Parameters can be concatenated with "&"

ParameterDescriptionRequired or Optional
?searchConfigName=myNameThis 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=10This query parameter defines how often to poll for data at the given task before giving up. Minimum value: 1Required
?interval=5000This query parameter defines the polling interval in msec. Minimum value: 100Required
Code Block
languagexml
<data>
	<field name="BaseDpEmployee_FirstName">Max</field>
	<field name="BaseDbEmployee_Photo">{base64EncodedPhoto}</field>
</data>

Response

In case of an Error you'll get the following status codes:

  • 400 - Bad Request
  • 500 - Internal Server error

Example responses

Code Block
titleExample: Error response with http status code 400
process definition [myProcess] with user-task [myTask] does not exist
Code Block
titleExample: Error response with http status code 400
maxAttempts must be at least 1
Code Block
titleExample: 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>

Response

In case of an Error you'll get the following status codes:

  • 400 - Bad Request
  • 500 - Internal Server error


Example responses

Code Block
languagexml
titleExample: 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>


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


Obtain task data

Expand
titleGET [root_context]/tasks/{processInstanceId}/{taskId}/data

Description

Obtains the data map 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


Code Block
[root_context]/tasks/{processInstanceId}/{taskId}/data


Method

GET

Header Parameters

ParameterDescriptionRequired 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


Example response


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

Execute task

Expand
titlePOST [root_context]/tasks/{processInstanceId}/{taskId}

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}

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


Start process, poll for data and execute task

Expand
titlePOST [root_context]/processes/{processDefinitionKey}/startGetDataAndExecute/{taskId}

Description

This command will start a process. The process is expected to reach a user task without further interaction. The command will try to fetch the process data at the user task and then execute the user task.

URL

Code Block
[root_context]/processes/{processDefinitionKey}/startGetDataAndExecute/{taskId}

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

Code Block
application/xml


Header Parameters

ParameterDescriptionRequired 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


Request Parameters

Multiple Request Parameters can be concatenated with "&"

ParameterDescriptionRequired 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

Response

?searchConfigName=myNameThis 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=10This query parameter defines how often to poll for data at the given task before giving up. Minimum value: 1Required
?interval=5000This query parameter defines the polling interval in msec. Minimum value: 100Required


Body

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

Code Block
languagexml
<data>
	<field name="BaseDpEmployee_FirstName">Max</field>
	<field name="BaseDbEmployee_Photo">{base64EncodedPhoto}</field>
</data>


Response

In case of an Error you'll get the following status codes:

  • 400 - Bad Request
  • 500 - Internal Server error


Example responses

language
Code Block
xmltitleExample: Error response with http status code 500400
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<restError>
    <message>No core template with name "null" was found.</message>
</restError>
Code Block
languagexml
titleExample: Successful response
<?xml versionprocess definition [myProcess] with user-task [myTask] does not exist


Code Block
titleExample: Error response with http status code 400
maxAttempts must be at least 1


Code Block
titleExample: Error response with http status code 500
<?xml version="1.0" encoding encoding="UTF-8" standalone standalone="yes"?>
<process instanceId="4711"/>

Obtain task data

Example response
Expand
titleGET [root_context]/tasks/{processInstanceId}/{taskId}/data

Description

Obtains the data map 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

Code Block
[root_context]/tasks/{processInstanceId}/{taskId}/data

Method

GET

Header Parameters

ParameterDescriptionRequired 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

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


Code Block
languagexml
titleExample: 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>



Code Block
languagexml
titleExample: 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>


Code Block
languagexml
titleExample: 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>


Obtain task data and execute task if data available

Expand
titlePOST [root_context]/tasks/{processInstanceId}/{taskId}/dataExec

Description

Obtains the data map of a task for a given process instance. If data could be obtained, the task will then be executed. The process instance is given by the parameter processInstanceId. The task which data has to be obtained is given by the passed taskId.

URL


Code Block
[root_context]/tasks/{processInstanceId}/{taskId}/dataExec


Method

GET

Header Parameters

ParameterDescriptionRequired 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

Example responses

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

  • 204 - No Content

In case of an Error you'll get the following status codes:

  • 400 - Bad Request
  • 500 - Internal Server error
Code Block
titleExample: Error response with http status code 400
no running process with instance id [4711] exists


Code Block
titleExample: Error response with http status code 400
no task [myTask] exists on process with instance id [4711]


Code Block
languagexml
titleExample: 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>


Code Block
languagexml
titleExample: 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>



This article is valid for Smart ID 21.-04 and later.