Last updated Oct 7, 2021

Rate this page:

External imports schema and mapping

Introduction

Applications that perform data imports into Insight 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/insight/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 Insight objects. The initial assumption is that these two object types have two attributes each, one of them is their Insight label.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
  "$schema": "https://api.stg.atlassian.com/jsm/insight/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 ressemble something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "hardDrives": [
      {
          "id": "Hard drive ID",
          "label": "Hard drive label",
          "files": [
            {
              "path": "/file/path",
              "size": 123456
            }
          ]
        }
      ]
  }
}

Rate this page: