Create a mapping - Narrative I/O Knowledge Base

Create a mapping

curl --request POST \
  --url https://api-dev.narrative.io/mappings/companies/{company_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "attribute_id": 123,
  "dataset_id": 456,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "product.brand",
        "expression": "itemBrand"
      },
      {
        "path": "product.category",
        "expression": "itemCategory"
      },
      {
        "path": "product.id.type",
        "expression": "'SKU'"
      },
      {
        "path": "product.id.value",
        "expression": "itemID"
      }
    ]
  }
}
EOF

import requests

url = "https://api-dev.narrative.io/mappings/companies/{company_id}"

payload = {
    "attribute_id": 123,
    "dataset_id": 456,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "path": "product.brand",
                "expression": "itemBrand"
            },
            {
                "path": "product.category",
                "expression": "itemCategory"
            },
            {
                "path": "product.id.type",
                "expression": "'SKU'"
            },
            {
                "path": "product.id.value",
                "expression": "itemID"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attribute_id: 123,
    dataset_id: 456,
    mapping: {
      type: 'object_mapping',
      property_mappings: [
        {path: 'product.brand', expression: 'itemBrand'},
        {path: 'product.category', expression: 'itemCategory'},
        {path: 'product.id.type', expression: '\'SKU\''},
        {path: 'product.id.value', expression: 'itemID'}
      ]
    }
  })
};

fetch('https://api-dev.narrative.io/mappings/companies/{company_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/mappings/companies/{company_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attribute_id' => 123,
    'dataset_id' => 456,
    'mapping' => [
        'type' => 'object_mapping',
        'property_mappings' => [
                [
                                'path' => 'product.brand',
                                'expression' => 'itemBrand'
                ],
                [
                                'path' => 'product.category',
                                'expression' => 'itemCategory'
                ],
                [
                                'path' => 'product.id.type',
                                'expression' => '\'SKU\''
                ],
                [
                                'path' => 'product.id.value',
                                'expression' => 'itemID'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/mappings/companies/{company_id}"

	payload := strings.NewReader("{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mappings/companies/{company_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/mappings/companies/{company_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  "attribute_id": 1,
  "created_at": "2021-12-10T00:00:00Z",
  "dataset_id": 3,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "foo",
        "expression": "upper(`US Kennel ID`)",
        "dependencies": {
          "properties": [
            "US Kennel ID"
          ]
        }
      },
      {
        "path": "bar.baz.qux",
        "expression": "weight * 10000",
        "dependencies": {
          "properties": [
            "weight"
          ]
        }
      }
    ]
  },
  "status": "active",
  "updated_at": "2021-12-10T00:00:01Z",
  "created_by": 1,
  "updated_by": 1,
  "company_id": 100,
  "scope": "global",
  "source": "admin",
  "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

POST

mappings

companies

{company_id}

Create a mapping

curl --request POST \
  --url https://api-dev.narrative.io/mappings/companies/{company_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "attribute_id": 123,
  "dataset_id": 456,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "product.brand",
        "expression": "itemBrand"
      },
      {
        "path": "product.category",
        "expression": "itemCategory"
      },
      {
        "path": "product.id.type",
        "expression": "'SKU'"
      },
      {
        "path": "product.id.value",
        "expression": "itemID"
      }
    ]
  }
}
EOF

import requests

url = "https://api-dev.narrative.io/mappings/companies/{company_id}"

payload = {
    "attribute_id": 123,
    "dataset_id": 456,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "path": "product.brand",
                "expression": "itemBrand"
            },
            {
                "path": "product.category",
                "expression": "itemCategory"
            },
            {
                "path": "product.id.type",
                "expression": "'SKU'"
            },
            {
                "path": "product.id.value",
                "expression": "itemID"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attribute_id: 123,
    dataset_id: 456,
    mapping: {
      type: 'object_mapping',
      property_mappings: [
        {path: 'product.brand', expression: 'itemBrand'},
        {path: 'product.category', expression: 'itemCategory'},
        {path: 'product.id.type', expression: '\'SKU\''},
        {path: 'product.id.value', expression: 'itemID'}
      ]
    }
  })
};

fetch('https://api-dev.narrative.io/mappings/companies/{company_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/mappings/companies/{company_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attribute_id' => 123,
    'dataset_id' => 456,
    'mapping' => [
        'type' => 'object_mapping',
        'property_mappings' => [
                [
                                'path' => 'product.brand',
                                'expression' => 'itemBrand'
                ],
                [
                                'path' => 'product.category',
                                'expression' => 'itemCategory'
                ],
                [
                                'path' => 'product.id.type',
                                'expression' => '\'SKU\''
                ],
                [
                                'path' => 'product.id.value',
                                'expression' => 'itemID'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/mappings/companies/{company_id}"

	payload := strings.NewReader("{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mappings/companies/{company_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/mappings/companies/{company_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attribute_id\": 123,\n  \"dataset_id\": 456,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"path\": \"product.brand\",\n        \"expression\": \"itemBrand\"\n      },\n      {\n        \"path\": \"product.category\",\n        \"expression\": \"itemCategory\"\n      },\n      {\n        \"path\": \"product.id.type\",\n        \"expression\": \"'SKU'\"\n      },\n      {\n        \"path\": \"product.id.value\",\n        \"expression\": \"itemID\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  "attribute_id": 1,
  "created_at": "2021-12-10T00:00:00Z",
  "dataset_id": 3,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "foo",
        "expression": "upper(`US Kennel ID`)",
        "dependencies": {
          "properties": [
            "US Kennel ID"
          ]
        }
      },
      {
        "path": "bar.baz.qux",
        "expression": "weight * 10000",
        "dependencies": {
          "properties": [
            "weight"
          ]
        }
      }
    ]
  },
  "status": "active",
  "updated_at": "2021-12-10T00:00:01Z",
  "created_by": 1,
  "updated_by": 1,
  "company_id": 100,
  "scope": "global",
  "source": "admin",
  "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

company_id

integer

required

Unique identifier for a company

Query Parameters

skip_validation

boolean

Skip validation of the mapping expressions against the query engine. Structural validation of the request still runs. The flag is enabled by being present; any value is ignored.

Body

application/json

attribute_id

integer

required

The target attribute's ID.

dataset_id

integer

required

The source dataset's ID.

mapping

object

required

Mapping definition for create/update requests. Dependencies are computed server-side and not provided by the client.

Option 1
Option 2
Option 3

Show child attributes

status

enum<string> | null

Status to create the mapping in. Defaults to active when omitted. Narrower than MappingStatus — a mapping cannot be created already archived.

Available options:

active,

pending,

null

Response

200 - application/json

string<uuid>

required

Unique identifier for a mapping.

Example:

"ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"

attribute_id

integer

required

The target attribute's ID.

created_at

string

required

ISO-8601 timestamp indicating when the mapping was created.

Example:

"2021-08-26T21:06:07.710357Z"

dataset_id

integer

required

The source dataset's ID.

mapping

object

required

Option 1
Option 2
Option 3

Show child attributes

status

enum<string>

required

The status of the mapping.

active - Active mappings can be used
archived - Archived/Deleted mappings - mapping no longer in use
pending - Pending mappings need to be accepted before they can be used
rejected - Proposed mappings the owner turned down. Can still be accepted later

Available options:

active,

archived,

pending,

rejected

updated_at

string

required

ISO-8601 timestamp indicating when the mapping was last updated.

Example:

"2021-08-26T21:06:07.710357Z"

created_by

integer<int64>

required

Unique id from a user who created it.

Example:

20

updated_by

integer<int64>

required

Unique id from a user who updated it.

Example:

20

scope

enum<string>

required

The scope of the mapping.

global - Mappings available to all
private - Company private mappings

Available options:

global,

private

source

enum<string>

required

The source of the mapping.

company - Company private mapping
admin - Admin created/promoted mapping
system - System (Automated/ML) mappings
lineage - Lineage-derived mappings (editable without admin)
rosetta_stone - Rosetta Stone mappings (editable without admin)
derived - Mappings produced by a derivation rule

Available options:

company,

admin,

system,

lineage,

rosetta_stone,

derived

company_id

integer<int64> | null

The company that owns the mapping. Null for platform-wide mappings.

Example:

345