Rate this page:
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.
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.
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 } ] } ] } }
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" } ] } }
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" } ] } } }
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.
Note that the following properties on existing entities can't be modified:
Object types, icons and attributes can't be deleted.
Following on our example schema above, let's see how we would modify it by:
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 } ] } ] } }
Rate this page: