For the list of all supported Decision Insight downloads and releases, see the Downloads page.

Mappings Web Services API

Learn how to use the mappings Web Services API.

Simple absorption service

This service allows data integrators to inject data into a node using a single mapping. To inject data using one or more mapping in a single transaction, use the full featured service.

Usage

The mapping is invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb/<space name>/<mapping name>

Example of HTTP body
{ 
  "customerName": "Acme Corp", 
  "category": "Entertainment",
  "vip": false
}

URI format

All requests must be POST request to the following URL:

<node url>/ws/absorb/<space name>/<mapping name>[?options]

URI options

Name Default value Description
wait false Whether or not the call to the Mapping should block until the absorption is complete

Examples 

POST: <node url>/ws/absorb/hvp/Create_Step?wait=true

Header format

All requests must include three HTTP headers:

Header Description

Authorization

Credentials of the user that wants to execute the mapping.

This user must have all the following permissions:

  • "Access data integration API" permission on the node
  • "Access" permission on the space of the mapping
  • "Data Collection" permission on the application with access to the space of the mapping

The credentials must be sent using the HTTP Basic authentication scheme (ex: Basic YWRtaW46YWRtaW4= )

Version Version of the API to use. Currently, the only supported value is 1.
Content-Type

Content type of the request. It must be set to either application/json, text/json or text/plain.

Body format

The request must contain in the body a JSON object containing the parameters declared for the mapping.

{
    "customerName": "Acme Corp",
    "vip": false
}

Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error.

Mapping parameter type JSON data type Example
Boolean boolean true
Decimal double 123.45
Duration
  • integer with the duration in milliseconds
  • ISO 8601 formatted duration string

1234

"PT1849S"

Instance
  • UUID string
  • long identifier

"dd68f200-8475-11e4-b4a9-0800200c9a66"

1487522985861449729

Instant
  • integer with the number of milliseconds since Unix epoch
  • ISO 8601 formatted date string
  • one of the following constants:
    • NOW
    • TODAY
    • YESTERDAY
    • FROM_START
    • UNTIL_END

1418660002223

"2014-12-15T16:13:22.223Z"

Integer integer 123
String string "Hello"

Response format

The response is a JSON object containing a single field: the transaction time of the absorbed request.

Here is a typical response:

HTTP response body
{
    "transactionTime": 1489114438022725600
}

Full featured absorption service

This service enables data integrators to inject data into a node using one or more mappings in a single transaction.

Usage

The Mappings are invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb

Example of HTTP body
[
  {
    "mapping": { 
      "space": "data-integration", 
      "name": "CreateOrUpdate_Customer"
    },
    "parameters": { 
      "customerName": "Acme Corp", 
      "category": "Entertainment",
      "vip": false
    }
  }
]

URI format

All requests must be POST request to the following URL:

<node url>/ws/absorb[?options]

URI options

Name Default value Description
wait false Whether or not the call to the Mapping should block until the absorption is complete

Examples 

POST: <node url>/ws/absorb?wait=true

Header format

All requests must include the same HTTP headers than expected by the simple absorption service: Authorization, Version and ContentType.

All expected headers are described here.

Body format

The request must contain in the body a JSON encoded list of MappingInput .

A MappingInput contains the information to specify a mapping, and the parameters to invoke the specified mapping.

Mapping

A mapping can be specified via its space & name

"mapping": {
    "space": "data-integration",
    "name": "CreatePayment"
}

or via its UUID

"mapping": "a130e899-8073-4ee3-b115-bc65ff5321d0"

Parameters

The parameters to supply are the one specified in the mapping screen in Data integration.

"parameters": {
    "customerName": "Acme Corp",
    "vip": false
}

Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error.

All accepted parameter types are described here.

Response format

The response is a JSON object containing a single field: the transaction time of the absorbed request.

Here is a typical response:

HTTP response body
{
    "transactionTime": 1489114438022725600
}

Examples

The following examples use the authorization token Basic YWRtaW46YWRtaW4= which is the uuencoded version of the default credentials of the admin user account (user: admin / password: admin).

If you have changed the default credentials of the admin account, you should replace the authorization token with valid uuencoded credentails.

Executing a mapping using the simple absorption service and waiting for the absorption to complete

Given the following mapping:

To absorb a customer using the simple absorption service and wait for the absorption to complete, you need to send the following HTTP request:

URL
POST: http://localhost:8080/ws/absorb/hvp/CreateOrUpdate_Customer?wait=true
HTTP Headers
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body
{
  "customerName": "Acme Corp",
  "category": "Entertainment",
  "vip": true
}

Executing a mapping with the full-featured service and waiting for the absorption to complete

Given the following mapping:

To absorb a customer using the web service and wait for the absorption to complete, you need to send the following HTTP request:

URL
POST: http://localhost:8080/ws/absorb?wait=true
HTTP Headers
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body
[
  {
    "mapping": {
      "name": "CreateOrUpdate_Customer",
      "space": "hvp"
    },
    "parameters": {
      "customerName": "Acme Corp",
      "category": "Entertainment",
      "vip": true
    }
  }
]

Executing two mappings in a single request

Given the following mappings: Create_Payment & Delete_Payment

 

To create and delete a payment using a single HTTP request, you would send the following request:


URL
POST: http://localhost:8080/ws/absorb
HTTP Headers
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body
[
  {
    "mapping": {
      "name": "Create_Payment",
      "space": "hvp"
    },
    "parameters": {
      "date": "2014-12-12T09:34:22.000",
      "paymentId": "1234-5678",
      "amount": 987.30,
      "emitter": "Acme Bank"
    }
  },
  {
    "mapping": {
      "name": "Delete_Payment",
      "space": "hvp"
    },
    "parameters": {
      "date": "2014-12-12T11:02:37.000",
      "paymentId": "1234-5678"
    }
  }
]

This is similar to grouping absorptions when invoking the mappings in a route.

Absorbing multiple instances in a single request

Given the following mapping:

To absorb three customers using the web service, you need to send the following HTTP request:

URL
POST: http://localhost:8080/ws/absorb
HTTP Headers
Authorization: Basic YWRtaW46YWRtaW4=
Version: 1
Content-Type: application/json
HTTP body
[
  {
    "mapping": {
      "name": "CreateOrUpdate_Customer",
      "space": "hvp"
    },
    "parameters": {
      "customerName": "Acme Corp",
      "category": "Entertainment",
      "vip": false
    }
  },
  {
    "mapping": {
      "name": "CreateOrUpdate_Customer",
      "space": "hvp"
    },
    "parameters": {
      "customerName": "AmerTek",
      "category": "Military",
      "vip": true
    }
  },
  {
    "mapping": {
      "name": "CreateOrUpdate_Customer",
      "space": "hvp"
    },
    "parameters": {
      "customerName": "Big Belly Burger",
      "category": "Restaurants",
      "vip": false
    }
  }
]



Related Links