Cool Data Mover API documentation
Introduction
This document describes the API that is offered by the Cool Data Mover. Via this API, customer are able to get a list of available packages, start a run for a package and retrieve the status of that run.
The API is a REST service named CoolDataMover offered from the CDM_API module. Its methods are available via the HTTPS protocol.
The service description is available at
https://<yourenvironment>/CDM_API/rest/CoolDataMover
A swagger specification is available at https://<yourenvironment>/CDM_API/rest/CoolDataMover/swagger.json
In this document we use the term BaseURL meaning https://<yourenvironment>/CDM_API/rest/CoolDataMover
Consuming the API
We highly recommend consuming the CDM_API using its swagger specification. This will ensure a seamless experience because within the swagger specification all technical details of passing parameter are defined.
When consuming within Outsystems this can be achieved by
- consuming a new REST API
- selecting the ‘Add multiple methods’ option
- specifying the service description URL (see above).
Outsystems will read the swagger specification and allow you to select the methods to consume.
API Key
All API methods are secured via an API key. The API key is environment specific and is registered in the APIKey site property of the CDM_API module. A unique value of this key is generated upon the first installation of the Cool Data Mover.
The API key needs to be supplied with every call to the API.
You are free to change the APIKey at will but you will have to make sure all authorized consumers of your CDM API are supplied with the new APIKey value.
The API key needs to be passed in the URL.
Status structure
Every method of the API returns a Status structure which indicates that status of the API call. The Boolean Success indicates whether the API call has been successful and an message describing the error that has occurred is specified in the ErrorMessage field in case the API call failed.
Method GetPackages
Retrieves a list off all available packages.
HTTP method | GET |
URL | <BaseURL>/v1/Packages |
Version | 1 |
Request parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
APIKey | Text | Mandatory (URL) | The API key |
Response parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
PackageId | Long | Mandatory | The id of the package |
PackageName | Text | Mandatory | The name of the package |
Description | Text | Mandatory | The description of the package |
ForImport | Boolean | Optional | Indicates whether the package can be used for imports. When not returned the package cannot be used for imports. |
ForExport | Boolean | Optional | Indicates whether the package can be used for exports. When not returned the package cannot be used for exports. |
ForDelete | Boolean | Optional | Indicates whether the package can be used for deletes. When not returned the package cannot be used for deletes. |
Example
Request URL (GET)
https://osprod.mycompany.com/CDM_API/rest/CoolDataMover/v1/Packages?APIKey=368ecff7-f70d-4fe9-b3a9-4f2254932c30
Request Body
<Empty>
Response body
{ "Packages":[
{ "PackageId":4,
"PackageName":"Sales application",
"ForImport":true,
"ForExport":true
}, {
"PackageId":8,
"PackageName":"MasterData",
"ForImport":true,
"ForExport":true
}, {
"PackageId":10,
"PackageName":"Test package",
"ForImport":true,
"ForDelete":true
}
],
"Status":{ "Success":true }
}
Method StartPackageRun
Starts a new import, export or delete run for a package.
HTTP method | POST |
URL | /v1/PackageRun |
Version | 1 |
Request parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
APIKey | Text | Mandatory (URL) | The API key |
PackageName | Text | Optional | The name of the package |
MoveType | Integer | Mandatory | Indicates the type of the run to start 0 – Validate 1 – Export 2 – Import 3 – Delete |
StartedByName | Text | Optional | The name of the person or system that requests the new package run. This name is shown in the run logs. |
ApplyCustomFilter | Boolean | Optional Default False | Applicable for exports only. Indicates whether to apply custom filtering during export. The option to support custom filtering has to be enabled in the package settings. |
CustomFilterName | Text | Optional. Mandatory when ApplyCustomFilter = True | The name of the filter to apply |
CustomFilterVariables | List | Optional. Mandatory when ApplyCustomFilter = True and the filter contains variables | A list of name, value pairs specifying the values to use for the variables in the filter |
-Name | Mandatory | The name of the filter variable | |
-Value | Mandatory | The value of the filter variable in text format. See table below for formatting instructions. | |
ApplyTenantFilter | Boolean | Optional Default False | Applicable for exports and deletes only. Indicates whether to apply tenant filtering. The option to support tenant filtering must be enabled in the package settings. |
TenantFilter_UserProviderName | Text | Optional. Mandatory when ApplyTenantFilter = True | The name of the user provider of the tenant |
TenantFilter_TenantName | Text | Optional. Mandatory when ApplyTenantFilter = True | The name of the tenant to be used during tenant filter during export/delete. |
ApplyProcessFilter | Boolean | Optional Default False | Indicates whether to apply process instance filtering. The option to allow BPT moves has to be enabled in the package settings. |
ProcessFilter_Status | Text | Optional. Mandatory when ApplyProcessFilter = True | Possible values: All, Not closed, Active, Closed, Suspended, Terminated |
ProcessFilter_StartedFrom | DateTime | Optional. Mandatory when ApplyProcessFilter = True | Specifies the start of the timespan in which the process instances to export/delete are started. |
ProcessFilter_StartedTo | DateTime | Optional. Mandatory when ApplyProcessFilter = True | Specifies the end of the timespan in which the process instances to export/delete are started. |
Filter variable value formatting
The value of filter variables is always supplied as text and must be formatted according to the corresponding datatype of the attribute.
Data type | Format | Example(s) |
---|---|---|
Boolean | True or False | True, False |
Currency | [-]xxxxxx.yyyy | 0.0, 10.0, -123456.78, 20.5678 |
Date | yyyy-mm-dd | 2021-12-31 |
DateTime | yyyy-MM-dd hh:mm:ss | 2021-12-31 23:59:59 |
Decimal | [-]xxxxxx.yyyy | 0.0, 10.0, -123456.78, 20.5678 |
No format | coolcdm@coolprofs.com | |
Integer | [-]xxxxxxxxx | 0, 20, -20 |
LongInteger | [-]xxxxxxxxxxxx | 0, 20, -20 |
PhoneNumber | No format | +31 (71) 331 1623 |
Text | No format | AnyText |
Time | hh:mm:ss | 23:59:59 |
Response parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
PackageRunId | Long | Mandatory | The id of the new PackageRun |
Status | Struct | Mandatory | Status |
Examples
Basic request to start a run
Request URL (POST)
https://osprod.mycompany.com/CDM_API/rest/CoolDataMover/v1/PackageRun?APIKey=368ecff7-f70d-4fe9-b3a9-4f2254932c30
Request Body
{"PackageName":"Sales application",
"MoveType":1
}
Response body
{ "PackageRunId":83,
"Status":
{"Success":true}
}
Request to start a run using a filter containing a variable
Request URL (POST)
https://osprod.mycompany.com/CDM_API/rest/CoolDataMover/v1/PackageRun?APIKey=368ecff7-f70d-4fe9-b3a9-4f2254932c30
Request Body
{ "PackageName":"Sales application",
"MoveType":1,
"ApplyCustomFilter":true,
"CustomFilterName":"Customer_SelectByRegion",
"StartedByName":"John Doe",
"CustomFilterVariables":[
{
"Name":"RegionCode",
"Value":"NL"
}
]
}
Response body
{ "PackageRunId":85,
"Status":
{"Success":true}
}
Method GetPackageRunStatus
Retrieves the status of a specified package run.
HTTP method | GET |
URL | /v1/PackageRun |
Version | 1 |
Request parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
APIKey | Text | Mandatory (URL) | The API key |
PackageId | Long | Optional (URL) | The id of the package. You need to specify either the PackageId, the PackageName or both. |
PackageName | Text | Optional (URL) | The name of the package. You need to specify either the PackageId, the PackageName or both. |
PackageRunId | Long | Optional (URL) | The id of the PackageRun to retrieve information on. When not specified the information of the last run for the specified package is returned. |
Response parameters
Attribute | Type | Optionality | Description |
---|---|---|---|
PackageRunId | Long | Mandatory | The id of the PackageRun |
MoveType | Integer | Mandatory | Indicates the type of the run 0 – Validate 1 – Export 2 – Import 3 – Delete |
PackageId | Long | Mandatory | The id of the package of the run |
PackageName | Text | Mandatory | The name of the package of the run |
StartedOn | DateTime | Mandatory | The datetime the run has started |
FinishedOn | DateTime | Optional | Date and time the run finished. The nulldate() (1900-01-1) is returned when the run has not finished. |
RunStatus | Text | Mandatory | The status of the run. Possible values: ToDo, InProgress, Done, Error, Aborted |
Status | Struct | Mandatory | Status |
Example
Request URL (GET)
https://osprod.mycompany.com/CDM_API/rest/CoolDataMover/v1/PackageRun?APIKey=368ecff7-f70d-4fe9-b3a9-4f2254932c30&PackageName=Sales+Application&PackageRunId=85
Request Body
<Empty>
Response body
{ "PackageRunId":85,
"MoveType":"1",
"PackageId":1,
"PackageName":"Sales application",
"StartedOn":"2022-03-02T11:49:59Z",
"FinishedOn":"2022-03-02T11:50:50Z",
"RunStatus":"Done",
"Status":{
"Success":true
}
}