Hello Atlassian Community,
We are in the process of importing multiple objects from an external source into Assets. To achieve this, we are utilizing the external import functionality and have been following the guidelines provided here: External Imports - Schema and Mapping.
We would like to inquire if there is a method to leverage existing schema mappings that have been defined through previous JSON imports or CSV imports via the web interface. Specifically, is there a way to reuse these mappings to streamline our current import process?
Additionally, are there any tools or features available that can dynamically generate the required mapping configurations, thereby reducing the need for manual setup?
We attempted to retrieve the existing schema and mapping using the following REST API call:
bash
CopiaModifica
curl --request GET \
--url 'https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/importsource/{importSourceId}/schema-and-mapping' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
However, this request returns only the schema without the mapping configuration. Is there a way to obtain both the schema and its associated mapping via the API?
We appreciate any insights or guidance you can provide on this matter.
Thank you.
The schema-and-mapping does include the mapping… if it has been defined. The process i followed was:
- Create the Schema in the Assets web UI
- Navigate to the Schema Settings
- Open the Import tab
- Click the Create Import button
- Choose External Import
- Set Name to my-import
- Click Create Import
- Click the … button for my-import, choose Generate new token
- Save in file my-import.token
- Get info with:
curl \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $(cat ./my-import.token)" \
--silent https://api.atlassian.com/jsm/assets/v1/imports/info
- Using the
mapping link, change the /mapping endpoint to /schema-and-mappingcurl \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $(cat ./my-import.token)" \
https://api.atlassian.com/jsm/assets/workspace/c3445a1c-ceb9-4f1f-97bf-53457ef289d7/v1/importsource/27e6d047-2dda-4eb2-b415-2d788ec003f3/schema-and-mapping \
> ./my-import.schema-and-mapping.json
- Edit the
mapping section (initially empty) to create an entry for each field:{
"schema": {
"objectSchema": {
"name": "Users Profile",
"description": "",
"objectTypes": [
{
"externalId": "cmdb::externalId/463500cb-d5ae-4579-8d27-7454afbc2824",
"name": "Users",
"description": "",
"inheritance": false,
"attributes": [
{
"externalId": "cmdb::externalId/0bd1497a-c0fb-4a3d-b234-ec097c8f8224",
"name": "Key",
"description": "",
"type": "text",
"label": false,
"minimumCardinality": 1,
"maximumCardinality": 1,
"unique": false
},
{
"externalId": "cmdb::externalId/c66e37af-a9d6-405e-80eb-8e02e28c09d3",
"name": "Name",
"description": "The name of the object",
"type": "text",
"label": true,
"minimumCardinality": 1,
"maximumCardinality": 1,
"unique": false
},
...
]
}
]
},
"iconSchema": {
"icons": [
{
"key": "user-icon",
"name": "User Icon",
"png48": "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"
}
]
}
},
"mapping": {
"objectTypeMappings": [
{
"attributesMapping": [
{
"attributeExternalId": "cmdb::externalId/c66e37af-a9d6-405e-80eb-8e02e28c09d3",
"attributeLocators": [
"name"
],
"attributeName": "Name"
},
...
],
"description": "Mapping for Users",
"objectTypeExternalId": "cmdb::externalId/463500cb-d5ae-4579-8d27-7454afbc2824",
"objectTypeName": "Users",
"selector": "user"
}
]
}
}
where each attributeMapping points at an entry from the schema by matching the attributeExternalId to the schemas externalId.
- Note: per the comment below, the
iconSchema section may be omitted if you are not adding any icons, but if present, it MUST have at least one icon definition in it.
- Update the mapping by posting to the
/mapping endpoint:curl \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $(cat ./my-import.token)" \
--silent \
--request PATCH \
--data "@my-import.schema-and-mapping.json" \
https://api.atlassian.com/jsm/assets/workspace/c3445a1c-ceb9-4f1f-97bf-53457ef289d7/v1/importsource/27e6d047-2dda-4eb2-b415-2d788ec003f3/mapping
- Query the
schema-and-mapping again and see your mapping:curl \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $(cat ./my-import.token)" \
https://api.atlassian.com/jsm/assets/workspace/c3445a1c-ceb9-4f1f-97bf-53457ef289d7/v1/importsource/27e6d047-2dda-4eb2-b415-2d788ec003f3/schema-and-mapping
@ibuchanan , the response returned back from the initial schema-and-mapping endpoint contains a section for icon:
...,"iconSchema":{"icons":[]}},...
This makes it feel like this section should be returned in the response with any additional icons you might want to include. However, if you try to submit it back as is, you get:
{"jsonValidationErrors":[{"type":"minItems","code":"1016","message":"$.schema.iconSchema.icons: must have at least 1 items but found 0","instanceLocation":"$.schema.iconSchema.icons","evaluationPath":"$.properties.schema.properties.iconSchema.properties.icons.minItems","schemaLocation":"https://api.atlassian.com/jsm/assets/imports/external/schema/versions/2023_10_19#/properties/schema/properties/iconSchema/properties/icons/minItems","messageKey":"minItems","arguments":[1,0]}],"dataValidationErrors":[],"status":"error"}
While this message and behavior are correct (per the json schema), it is definitely confusing to the new users. As you can see in my steps above, i went the route of adding an unused icon just so the error would go away. The other supported approach is to remove the iconSchema section because it is optional (though if present, you must have at least one value in icons).
I think there are two options that would be a far better user experience here:
- Given that this process starts from an existing schema, the icons section should return the reference to the image currently being used for that schema.
- Do not return an
iconSchema section for the schema-and-mappings endpoint if it doesn’t contain any icons (thus violating its own schema)
Thanks for your reply. I resolved this issue last year. I usually remove the icon section from the schema, and it was working.
What I still have an issue with is the user attribute — it seems it’s not supported yet. Did you find any workaround for that?
Thanks for your help.
@LucasTheisen,
Thanks for the feedback. I’ll raise this with some of the other observations I’ve had spinning up the sample app and trying to improve the docs.
