Rate this page:
As opposed to the other three types of import, external imports don't require the customer to provide a file with data when they create the import configuration. Instead, the customer obtains a OAuth token that an external application or script can use to push data into Assets.
In this step, the customer creates an external import source in Assets, and generates a OAuth token for it. They will then provide the token to the external app.
In this step, the external app will verify the OAuth token supplied by the customer is valid and was generated for an Assets external import source. The external application can do this by performing a GET request to the imports info endpoint in Assets:
1 2GET https://api.atlassian.com/jsm/assets/v1/imports/info Accept: application/json Authorization: Bearer EXAMPLE_TOKEN
If the token is valid and can be used, Assets will respond with a set of links that can be used to continue with the workflow:
1 2{ "links": { "getStatus": "https://api.atlassian.com/jsm/assets/workspace/...", "start": "https://api.atlassian.com/jsm/assets/workspace/...", "mapping": "https://api.atlassian.com/jsm/assets/workspace/..." } }
These three links give the external app the full URLs it needs to invoke in order to:
getStatus
)start
)mapping
)Note that the URLs returned by this endpoint are to be used exclusively with the token that was used to obtain them, and they shouldn't be stored or manipulated.
External apps can perform a GET request to the getStatus
endpoint (with URL as obtained in step 2).
This endpoint returns a JSON object that represents the current status of the import source:
1 2{ "status": "IDLE" }
The mapping configuration could be in any of these states:
Third party tools must submit their schema and mapping configuration prior to running imports.
External import sources will fail to start, and will report in MISSING_MAPPING
status until this
happens.
The URL to submit the mapping was obtained in step 2, as the mapping
link, and can be invoked with
a PUT:
1 2PUT https://api.atlassian.com/jsm/assets/workspace/... Accept: application/json Authorization: Bearer EXAMPLE_TOKEN Content-Type: application/json { ... schema and mapping ... }
The schema and mapping can be modified later on by invoking the same URL with a PATCH call.
See the object schema and mapping guide for more information on how to write an object schema and mapping configuration for external imports.
When ready to kick off an import, the third party app should perform a POST request to the URL
obtained in step 2 as start
1 2POST https://api.atlassian.com/jsm/assets/workspace/... Accept: application/json Authorization: Bearer EXAMPLE_TOKEN
If the import source was in the IDLE
status, Assets will create a new import execution. The
response will be:
1 2{ "result": "success", "links": { "submitProgress": "https://api.atlassian.com/...", "submitResults": "https://api.atlassian.com/...", "getExecutionStatus": "https://api.atlassian.com/...", "cancel": "https://api.atlassian.com/..." } }
This set of links can be used to:
submitProgress
)submitResults
)getExecutionStatus
)cancel
)As the external tool is now generating data from is internal or external sources, it can report back to Assets with progress information. While this isn't necessary from an API point of view (the import will complete with or without it), it can provide for a better user experience - specially if the customer doesn't have access to the external app's UI but they can access Assets
This operation can be invoked repeatedly while the import hasn't been transitioned to PROCESSING
,
and each call overwrites the previous ones. To report progress, invoke the submitProgress
URL
obtained in step 4 with a PUT
:
1 2PUT https://api.atlassian.com/... Accept: application/json Authorization: Bearer EXAMPLE_TOKEN Content-Type: application/json { "steps": { "total": 3, "current": 2, "description": "Gathering data" }, "objects": { "total": 500, "processed": 125 } }
At least one of steps
and objects
must be present.
The data to import is submitted by the external app to Assets in a series of data sets - or chunks. The app can submit as many chunks as it needs - they will be stored and processed only when the end of data is signaled.
Data chunks can be submitted by performing a POST request to the submitResults
link obtained in step 4.
The request body can optionally contain a field clientGeneratedId
. If present, Assets will ignore the request
if a chunk with the same identified has already been submitted. You can therefore ensure idempotent calls to Assets
by always assigning the same clientGeneratedId
to the same chunks of data, even when you retry a request due a network error for example.
1 2{ "data": { ... your JSON import data ... }, "clientGeneratedId": "a-unique-id" }
This operation will create the chunk and store it - data won't be processed yet. The external application can continue to submit chunks and report progress, until data completion is signaled.
You can see an example of schema and mapping configuration along with a matching data chunk in the object schema and mapping guide
In order to signal data completion, the external application must perform a request to the submitResults
endpoint
with a completed
field set to true:
1 2{ "completed": true }
Assets will now start processing the submitted data chunks. No further data chunks or progress reports can be provided for this import execution, and no other import execution can be created for the same import source until this process is finished.
Customers can track the status of their import using Assets' user interface. Once data processing is complete the import source will return to IDLE status, so a new import can be subsequently started in the future by repeating step 4.
Note: You can combine a chunk with the use of the completed
field, by submitting data and marking
the import as completed all at once:
1 2{ "data": { ... import data ... }, "clientGeneratedId": "a-unique-id", "completed": true }
This is equivalent to invoking the endpoint twice, first with the data chunk and then with the data completion signal.
Apps can use their own structure in the data
field of their chunks. Assets will strip the root data
field, and store its
whole value as its own JSON file. It will then be processed the same way a JSON import would process such file.
Therefore, your selectors and mapping shouldn't include the data
prefix.
External applications can cancel an import execution they have started as long as they haven't signalled data completion.
For this purpose, a DELETE should be performed against the cancel
endpoint URL as obtained in step 4.
1 2DELETE https://api.atlassian.com/... Accept: application/json
This will return the import source to IDLE, so a new import can be subsequently started in the future by repeating step 4.
Rate this page: