Public REST API documentation

General information

For using the public REST API two steps are necessary for all the following curl commands. First step is how to find the public REST API and second is to authenticate against the server.

Where to find the endpoints

The endpoints could be found with the UI or Core url and the suffix '/api/public'. In the lower curl commands, 'https://xdm.ubs-hainer.com:80/' must be replaced with the following to use the public REST API <protocol>://<server>:<port>/<context-path>/api/. For example an exact example how the url with context path of a running execution looks like this:

https://xdm.ubs-hainer.com/prod/api/public/execute/1

In the above example /prod is the configured context path of the XDM UI.

Authentication

To use the public REST API it is necessary to authenticate against the server. This can be done directly in the curl command with the following command:

-u '<user>':'<password>'

Overview

HTTP status codes

An invocation of REST endpoints also returns a status code. The following standard HTTP codes can be returned by the public REST API of XDM:

Status code Usage

200 OK

The request completed successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist. For instance this error occurs if an object like a task, or template could not be found.

412 Precondition Failed

The request could not be processed, because the request payload is invalid, or required parameter have not been provided.

504 Gateway timeout

This indicates that the request got a timeout. For instance this status code can occur, if a task execution takes longer than the specified timeout.

Execute by object url

A POST request to execute an object specified by its self URL. The object can be a task, task template, workflow or workflow template.

If a workflow or task template is executed the caller can provide values for custom parameters. These custom parameters must be defined on the respective object.

Executions of templates always cause the creation of a new workflow, or task for each execution. The newly created object contains all overwritten properties that have been provided by the caller of this endpoint.

Request fields

Path Optional Default Type Description

objectUrl

false

 — 

String

Specifies the URL of the object that should be executed. The URL must address the XDM core service, or the UI service directly.

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

parameters

true

 — 

Object

A list of key-value pairs specifying parameters to override for this particular call. The parameter name refers to the internal name of the parameter. A value for a custom parameter can be specified by it’s variable name. The display name of an object must be specified if the parameter value references an XDM object. If the parameter is a custom parameter and has option entries, the value of the parameter must be must be the name of the object associated with the option entry. You cannot specify the value as specified in the option entry mapping.

credentials

true

 — 

Object

List of user and password pairs. The specified users/passwords are used to connect to a source or target database system. The caller of this REST endpoint can provide alternative passwords. The user name must match a user specified for any involved connection.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "objectUrl" : "https://xdm.ubs-hainer.com/api/task-template/native-table-copy-task-template/1/task/2",
  "parameters" : {
    "customParameterName" : "Its value"
  },
  "credentials" : {
    "john.doe" : "johns_secret"
  },
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Execute task template by name

A POST request to execute a task template by its name. The request can provide values for custom parameter. The custom parameters must be defined on the respective task template. A new task will be created for each execution of the task template. This task includes all overwritten custom parameters.

Request fields

Path Optional Default Type Description

taskTemplate

false

 — 

String

Specifies the name of the task template that should be executed.

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

parameters

true

 — 

Object

A list of key-value pairs specifying parameters to override for this particular call. The parameter name refers to the internal name of the parameter. A value for a custom parameter can be specified by it’s variable name. The display name of an object must be specified if the parameter value references an XDM object. If the parameter is a custom parameter and has option entries, the value of the parameter must be must be the name of the object associated with the option entry. You cannot specify the value as specified in the option entry mapping.

credentials

true

 — 

Object

List of user and password pairs. The specified users/passwords are used to connect to a source or target database system. The caller of this REST endpoint can provide alternative passwords. The user name must match a user specified for any involved connection.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "taskTemplate" : "Demo task template",
  "parameters" : {
    "customParameterName" : "Its value"
  },
  "credentials" : {
    "john.doe" : "johns_secret"
  },
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Execute task by name

A POST request to execute a task specified by the task template and task name.

Request fields

Path Optional Default Type Description

taskTemplate

false

 — 

String

Specifies the name of the task template of which the task should be executed.

task

false

 — 

String

Specifies the task name which should be executed.

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

credentials

true

 — 

Object

List of user and password pairs. The specified users/passwords are used to connect to a source or target database system. The caller of this REST endpoint can provide alternative passwords. The user name must match a user specified for any involved connection.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "task" : "Demo task",
  "taskTemplate" : "Demo task template",
  "credentials" : {
    "john.doe" : "johns_secret"
  },
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Execute workflow template by name

A POST request to execute a workflow template by its name. The request can provide values for custom parameter. The custom parameters must be defined on the respective workflow template. A new workflow will be created for each execution of the workflow template. This workflow includes all overwritten custom parameters.

Request fields

Path Optional Default Type Description

workflowTemplate

false

 — 

String

Specifies the name of the workflow template that should be executed.

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

parameters

true

 — 

Object

A list of key-value pairs specifying parameters to override for this particular call. The parameter name refers to the internal name of the parameter. A value for a custom parameter can be specified by it’s variable name. The display name of an object must be specified if the parameter value references an XDM object. If the parameter is a custom parameter and has option entries, the value of the parameter must be must be the name of the object associated with the option entry. You cannot specify the value as specified in the option entry mapping.

credentials

true

 — 

Object

List of user and password pairs. The specified users/passwords are used to connect to a source or target database system. The caller of this REST endpoint can provide alternative passwords. The user name must match a user specified for any involved connection.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "workflowTemplate" : "Demo workflow template",
  "parameters" : {
    "customParameterName" : "Its value"
  },
  "credentials" : {
    "john.doe" : "johns_secret"
  },
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Execute workflow by name

A POST request to execute a workflow specified by the workflow template and workflow name.

Request fields

Path Optional Default Type Description

workflowTemplate

false

 — 

String

Specifies the name of the workflow template of which the workflow should be executed.

workflow

false

 — 

String

Specifies the workflow name which should be executed.

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "workflow" : "Demo workflow",
  "workflowTemplate" : "Demo workflow template",
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Execute data shop by name

A POST request to execute a data shop specified by its name. The request can provide values for form parameter. The form parameters must be defined on the respective data shop.

Request fields

Path Optional Default Type Description

dataShop

false

 — 

String

Specifies the name of the data shop that should be executed

waitForCompletion

true

false

Boolean

If this flag is set to true the invocation of the endpoint will return as soon as the task execution has been finished. A value of false will not block the endpoint and the invocation immediately returns. In this case the caller must manually poll the status to find out when the execution is finished.

waitTimeoutSeconds

true

3600

Number

Specifies the number of seconds that the endpoint should maximal wait until the execution completes. If the execution takes longer than the specified seconds, the endpoints returns with a timeout indicated by http status code 504.

parameters

true

 — 

Object

A list of key-value pairs specifying parameters to override for this particular call. The parameter name refers to the internal name of the parameter. A value for a custom parameter can be specified by it’s variable name. The display name of an object must be specified if the parameter value references an XDM object. If the parameter is a custom parameter and has option entries, the value of the parameter must be must be the name of the object associated with the option entry. You cannot specify the value as specified in the option entry mapping.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/execute' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "dataShop" : "Demo data shop",
  "parameters" : {
    "customParameterName" : "Its value"
  },
  "waitForCompletion" : true,
  "waitTimeoutSeconds" : 3600
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 275

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/api/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Retrieve execution status

A GET request to retrieve the current status of the provided task execution.

Path parameters

Table 1. /public/execute/{task-execution-id}
Parameter Description

task-execution-id

The numeric ID of the task execution that should be returned by the endpoint.

Curl request

$ curl 'https://xdm.ubs-hainer.com/public/execute/33' -i -X GET \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 271

{
  "startTime" : "2021-01-01T10:11:00",
  "endTime" : "2021-01-01T10:25:00",
  "status" : "UNKNOWN",
  "exitCode" : 0,
  "exitDescription" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://xdm.ubs-hainer.com/public/execute/33",
    "type" : "GET"
  } ]
}

Response fields

Path Type Description

startTime

Timestamp

The date and time when the execution started

endTime

Timestamp

The date and time when the execution finished. This field might be null if the execution is still running

exitCode

Number

A numeric exit code that indicates if the execution was successful, or not. A value of zero indicates a successful execution. This field is null if the execution is still running

exitDescription

String

This field contains a error message if the execution failed. Otherwise the field is null

status

String

The current status of the execution. Possible values are:

COMPLETE

The execution finished successful

RUNNING

The execution is still running

UNKNOWN

The status of the execution could not be determined

ERROR

The execution failed. In this case the errorDescription might indicate more details about the cause of the problem.

CANCELED

The execution was canceled by a user

REJECTED

The execution was rejected by a authorized user

WAITING

The execution did not yet start and waits for a free executor.

links

Array

Links to the execution resource

Export xdm objects

A POST request to export one or more xdm objects as a yaml file.

Request fields

Path Optional Default Type Description

objectUrls

false

 — 

String

Specifies the list of objects that should be exported. An URL can identify a specific object or a list of objects. In case of a list all objects of the list are exported.

includeChildren

true

false

Boolean

Dependent are objects that only belong to the exported object like rules, permissions & tasks.

includeDependentObjects

true

false

Boolean

Referenced objects exist by their own and can be used by the exported object like connections & environments.

includeDependentObjectsChildren

true

false

Boolean

Also include the dependent objects of the referenced objects. E.g. the rules of a modification set or the rules in a application model version.

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/export' -i -X POST \
    -H 'Accept: application/hal+json' \
    -d '{
  "objectUrls" : [ "https://xdm.ubs-hainer.com/api/task-template/native-table-copy-task-template/2" ],
  "includeChildren" : true,
  "includeDependentObjects" : true,
  "includeDependentObjectsChildren" : true
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/yml
Accept-Ranges: bytes

Import xdm objects

A 'POST' request to import xdm objects.

Request parts

Part Description

file

Specifies the path to the file which should be imported. While using curl the path to the file must start with the @ sign, otherwise a http status 400 (BAD_REQUEST) is returned by the endpoint invocation

Curl request

$ curl 'https://xdm.ubs-hainer.com/api/public/import' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/hal+json' \
    -F 'file=@<your-file-path>'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 168

[ {
  "displayName" : "Demo credential",
  "objectUrl" : "https://xdm.ubs-hainer.com/api/credential/1",
  "action" : "CREATED",
  "reason" : "",
  "property" : null
} ]

Response fields

Path Type Description

[]

Array

A list of imported objects.

[].displayName

String

The name of the imported object.

[].objectUrl

String

The url to the imported object.

[].action

String

The action of the import. Possible values are:

CREATED

The import created the object successfully.

REPLACED

The object already existed. The import replaced the object with the attributes defined in the YAML file.

SKIPPED

The imported object was skipped. Please refer to the reason field to determine the cause why the object has been skipped.

[].reason

String

Describes the reason why the object was not imported.

[].property

Null

The property that causes the reason.