TOC
< All

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 methodGET
URL<BaseURL>/v1/Packages
Version1

Request parameters

AttributeTypeOptionalityDescription
APIKeyTextMandatory (URL)The API key

Response parameters

AttributeTypeOptionalityDescription
PackageIdLongMandatoryThe id of the package
PackageNameTextMandatoryThe name of the package
DescriptionTextMandatoryThe description of the package
ForImportBooleanOptionalIndicates whether the package can be used for imports. When not returned the package cannot be used for imports.
ForExportBooleanOptionalIndicates whether the package can be used for exports. When not returned the package cannot be used for exports.
ForDeleteBooleanOptionalIndicates 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 methodPOST
URL/v1/PackageRun
Version1

Request parameters

AttributeTypeOptionalityDescription
APIKeyTextMandatory (URL)The API key
PackageNameTextOptionalThe name of the package
MoveTypeIntegerMandatoryIndicates the type of the run to start
  0 – Validate
  1 – Export
  2 – Import
  3 – Delete
StartedByNameTextOptionalThe name of the person or system that requests the new package run. This name is shown in the run logs.
ApplyCustomFilterBooleanOptional
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.
CustomFilterNameTextOptional.
Mandatory when ApplyCustomFilter = True
The name of the filter to apply
CustomFilterVariablesListOptional.
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
-NameMandatoryThe name of the filter variable
-ValueMandatoryThe value of the filter variable in text format. See table below for formatting instructions.
ApplyTenantFilterBooleanOptional
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_UserProviderNameTextOptional.
Mandatory when ApplyTenantFilter = True
The name of the user provider of the tenant
TenantFilter_TenantNameTextOptional.
Mandatory when ApplyTenantFilter = True
The name of the tenant to be used during tenant filter during export/delete.
ApplyProcessFilterBooleanOptional
Default False
Indicates whether to apply process instance filtering. The option to allow BPT moves has to be enabled in the package settings.
ProcessFilter_StatusTextOptional.
Mandatory when ApplyProcessFilter = True
Possible values:
All, Not closed, Active, Closed, Suspended, Terminated
ProcessFilter_StartedFromDateTimeOptional.
Mandatory when ApplyProcessFilter = True
Specifies the start of the timespan in which the process instances to export/delete are started.
ProcessFilter_StartedToDateTimeOptional.
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 typeFormatExample(s)
BooleanTrue or FalseTrue, False
Currency[-]xxxxxx.yyyy0.0, 10.0, -123456.78, 20.5678
Dateyyyy-mm-dd2021-12-31
DateTimeyyyy-MM-dd hh:mm:ss2021-12-31 23:59:59
Decimal[-]xxxxxx.yyyy0.0, 10.0, -123456.78, 20.5678
EmailNo formatcoolcdm@coolprofs.com
Integer[-]xxxxxxxxx0, 20, -20
LongInteger[-]xxxxxxxxxxxx0, 20, -20
PhoneNumberNo format+31 (71) 331 1623
TextNo formatAnyText
Timehh:mm:ss23:59:59

Response parameters

AttributeTypeOptionalityDescription
PackageRunIdLongMandatoryThe id of the new PackageRun
StatusStructMandatoryStatus

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 methodGET
URL/v1/PackageRun
Version1

Request parameters

AttributeTypeOptionalityDescription
APIKeyTextMandatory (URL)The API key
PackageIdLongOptional (URL)The id of the package. You need to specify either the PackageId, the PackageName or both.
PackageNameTextOptional (URL)The name of the package. You need to specify either the PackageId, the PackageName or both.
PackageRunIdLongOptional (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

AttributeTypeOptionalityDescription
PackageRunIdLongMandatoryThe id of the PackageRun
MoveTypeIntegerMandatoryIndicates the type of the run
  0 – Validate
  1 – Export
  2 – Import
  3 – Delete
PackageIdLongMandatoryThe id of the package of the run
PackageNameTextMandatoryThe name of the package of the run
StartedOnDateTimeMandatoryThe datetime the run has started
FinishedOnDateTimeOptionalDate and time the run finished.  The nulldate() (1900-01-1) is returned when the run has not finished.
RunStatusTextMandatoryThe status of the run.
Possible values: ToDo, InProgress, Done, Error, Aborted
StatusStructMandatoryStatus

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