External Imports - Schema and mapping

Introduction

Applications that perform data imports into Assets must define their own object schema and mapping configuration. Check out the workflow of external imports guide to see how to obtain the URL for this endpoint from the user.

JSON structure and format

External imports object schema and mapping configurations are defined in a JSON document that conforms to Atlassian's " Imports Schema and Mapping definition" JSON schema. You can see the latest JSON schema definition here: https://api.atlassian.com/jsm/assets/imports/external/schema/versions/2021_09_15

If you want to learn more about JSON schema definitions and the tools that are available to you in your tech stack of choice, check out the JSON schema project.

Example schema and mapping document

The following schema and mapping document models two simple object types (Hard Disk and File) and their mapping into Assets objects. The initial assumption is that these two object types have two attributes each, one of them is their Assets label.

1
2
{
  "$schema": "https://api.stg.atlassian.com/jsm/assets/imports/external/schema/versions/2021_09_15",
  "schema": {
    "objectSchema": {
      "name": "Disk Analysis Tool",
      "description": "Data imported from The Disk Analysis Tool",
      "objectTypes": [
        {
          "name": "Hard Drive",
          "description": "A hard drive found during scanning",
          "attributes": [
            {
              "name": "DUID",
              "description": "Device Unique Identifier",
              "type": "text",
              "label": true
            },
            {
              "name": "Disk Label",
              "description": "Hard drive label",
              "type": "text"
            }
          ],
          "children": [
            {
              "name": "File",
              "description": "A file present in a hard drive",
              "attributes": [
                {
                  "name": "Path",
                  "description": "Path of the file",
                  "type": "text",
                  "label": true
                },
                {
                  "name": "Size",
                  "description": "Size of the file",
                  "type": "integer"
                }
              ]
            }
          ]
        }
      ]
    }
  },
  "mapping": {
    "objectTypeMappings": [
      {
        "objectTypeName": "Hard Drive",
        "selector": "hardDrives",
        "description": "Mapping for Hard Drives",
        "attributesMapping": [
          {
            "attributeName": "DUID",
            "attributeLocators": [
              "id"
            ],
            "externalIdPart": true
          },
          {
            "attributeName": "Disk Label",
            "attributeLocators": [
              "label"
            ]
          }
        ]
      },
      {
        "objectTypeName": "File",
        "selector": "hardDrives.files",
        "description": "Maps files found in hard drives",
        "attributesMapping": [
          {
            "attributeName": "Path",
            "attributeLocators": [
              "path"
            ],
            "externalIdPart": true
          },
          {
            "attributeName": "Size",
            "attributeLocators": [
              "size"
            ]
          }
        ]
      }
    ]
  }
}

As we defined our selector for the Hard Drive object as hardDrives, and the selector for File as hardDrives.files, our data structure should resemble something like this:

1
2
{
  "hardDrives": [
    {
      "id": "Hard drive ID",
      "label": "Hard drive label",
      "files": [
        {
          "path": "/file/path",
          "size": 123456
        }
      ]
    }
  ]
}

And so our data chunk payload when calling the submitResults endpoint would be:

1
2
{
  "data": {
    "hardDrives": [
      {
        "id": "Hard drive ID",
        "label": "Hard drive label",
        "files": [
          {
            "path": "/file/path",
            "size": 123456
          }
        ]
      }
    ]
  }
}

Reference type attributes

If we want an attribute to refer to another object we can set up a reference type attribute. We will need to tell Assets of which object type the referred object is and provide an object mapping AQL. The following schema and mapping document models two simple object types (Hard Disk and Operating System) and their mapping into Assets objects.

1
2
{
  "$schema": "https://api.stg.atlassian.com/jsm/assets/imports/external/schema/versions/2021_09_15",
  "schema": {
    "objectSchema": {
      "name": "Disk Analysis Tool",
      "description": "Data imported from The Disk Analysis Tool",
      "objectTypes": [
        {
          "name": "Hard Drive",
          "description": "A hard drive found during scanning",
          "attributes": [
            {
              "name": "DUID",
              "description": "Device Unique Identifier",
              "type": "text",
              "label": true
            },
            {
              "name": "Disk Label",
              "description": "Hard drive label",
              "type": "text"
            },
            {
              "name": "Operating System",
              "description": "OS currently on this hard drive",
              "type": "referenced_object",
              "referenceObjectTypeName": "Operating System"
            }
          ]
        },
        {
          "name": "Operating System",
          "description": "The operating system",
          "attributes": [
            {
              "name": "Name",
              "description": "The name of the operating system",
              "type": "text",
              "label": true
            },
            {
              "name": "Version",
              "description": "Operating system version",
              "type": "text"
            }
          ]
        }
      ]
    }
  },
  "mapping": {
    "objectTypeMappings": [
      {
        "objectTypeName": "Hard Drive",
        "selector": "hardDrives",
        "description": "Mapping for Hard Drives",
        "attributesMapping": [
          {
            "attributeName": "DUID",
            "attributeLocators": [
              "id"
            ],
            "externalIdPart": true
          },
          {
            "attributeName": "Disk Label",
            "attributeLocators": [
              "label"
            ]
          },
          {
            "attributeName": "Operating System",
            "attributeLocators": [
              "os"
            ],
            "objectMappingIQL": "Name Like ${os}"
          }
        ]
      },
      {
        "objectTypeName": "Operating System",
        "selector": "os",
        "description": "Mapping for OS",
        "attributesMapping": [
          {
            "attributeName": "Name",
            "attributeLocators": [
              "name"
            ],
            "externalIdPart": true
          },
          {
            "attributeName": "Version",
            "attributeLocators": [
              "version"
            ]
          }
        ]
      }
    ]
  }
}

As we defined our selector for the Hard Drive object as hardDrives, and the selector for Operating system as os, our data structure should resemble something like this:

1
2
{
  "hardDrives": [
    {
      "id": "Hard drive ID",
      "label": "Hard drive label",
      "os": "macOS Big Sur"
    }
  ],
  "os": [
    {
      "name": "macOS Big Sur",
      "version": "11.6.1"
    }
  ]
}

The objectMappingIQL will tell Assets that the object to be linked in the object reference attribute type matches the following AQL: Name Like ${os}

From the data provided in the above JSON the AQL will be interpolated to: Name Like "macOS Big Sur"

And so our data chunk payload when calling the submitResults endpoint would be:

1
2
{
  "data": {
    "hardDrives": [
      {
        "id": "Hard drive ID",
        "label": "Hard drive label",
        "os": "macOS Big Sur"
      }
    ],
    "os": [
      {
        "name": "macOS Big Sur",
        "version": "11.6.1"
      }
    ]
  }
}

Icons

Object types defined in your schema will be given a default icon, unless you specify a custom one for them. Define your custom icons in the schema.iconSchema object, and use them in your object type definitions:

1
2
{
  "schema": {
    "iconSchema": {
      "icons": [
        {
          "key": "a-unique-icon-key",
          "name": "User visible icon name",
          "png48": "48x48 pixels base64 encoded PNG icon"
        }
      ]
    },
    "objectSchema": {
      "objectTypes": [
        {
          "name": "Hard Drive",
          "description": "A hard drive found during scanning",
          "iconKey": "a-unique-icon-key"
        }
      ]
    }
  }
}

Modifying an existing schema

The mapping endpoint supports PATCH calls. The payload accepted by the PATCH operation conforms to the same JSON shape as the PUT operation, but you only need to include the object types and object mappings you wish to modify.

Supported operations

Existing object type and attribute descriptions can be modified.
Existing object type icons can be modified
New object types can be added to the schema
New attributes can be added to existing object types as well.
New icons can be added to the schema
Existing icons names and image data can be overwritten
Mapping definitions for object types can be overwritten

Note that the following properties on existing entities can't be modified:

Object type name
Attribute name
Attribute type
Referenced object type (for object reference attributes)
Icon keys

Object types, icons and attributes can't be deleted.

Example

Following on our example schema above, let's see how we would modify it by:

Adding a new attribute to the "Hard Drive" object type, called "Manufacturer"
Adding a new object type, "Folder", as a child of the existing object type "Hard Drive"
Changing the description of the existing attribute "Path" in the "File" object type

1
2
{
  "$schema": "https://api.stg.atlassian.com/jsm/assets/imports/external/schema/versions/2021_09_15",
  "schema": {
    "objectSchema": {
      "name": "Disk Analysis Tool",
      "description": "Data imported from The Disk Analysis Tool",
      "objectTypes": [
        {
          "name": "Hard Drive",
          "description": "A hard drive found during scanning",
          "attributes": [
            {
              "name": "Manufacturer",
              "description": "Manufacturer name",
              "type": "text"
            }
          ],
          "children": [
            {
              "name": "Folder",
              "description": "A folder present in a hard drive",
              "attributes": [
                {
                  "name": "Name",
                  "description": "Folder name",
                  "type": "text",
                  "label": true
                }
              ]
            },
            {
              "name": "File",
              "description": "A file present in a hard drive",
              "attributes": [
                {
                  "name": "Path",
                  "description": "Updated description for the path attribute",
                  "type": "text",
                  "label": true
                }
              ]
            }
          ]
        }
      ]
    }
  },
  "mapping": {
    "objectTypeMappings": [
      {
        "objectTypeName": "Hard Drive",
        "selector": "hardDrives",
        "description": "Mapping for Hard Drives",
        "attributesMapping": [
          {
            "attributeName": "DUID",
            "attributeLocators": [
              "id"
            ],
            "externalIdPart": true
          },
          {
            "attributeName": "Disk Label",
            "attributeLocators": [
              "label"
            ]
          },
          {
            "attributeName": "Manufacturer",
            "attributeLocators": [
              "manufacturer"
            ]
          }
        ]
      },
      {
        "objectTypeName": "Folder",
        "selector": "hardDrives.folders",
        "description": "Mapping for Folder",
        "attributesMapping": [
          {
            "attributeName": "Name",
            "attributeLocators": [
              "name"
            ],
            "externalIdPart": true
          }
        ]
      }
    ]
  }
}