Last updated Sep 19, 2022

Rate this page:

Overview of the workflow for external imports

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.

Step 1: Obtaining a OAuth token

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.

Step 2: Token verification

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
2
GET 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:

  • Get the current status of an import source (getStatus)
  • Start an import (start)
  • Initialize or modify the object schema and mapping for an import source (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.

Step 2b (optional): Fetch the status of the mapping configuration

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:

  • IDLE (the import source is ready, and an import can be started)
  • RUNNING (an import is currently running)
  • DISABLED (the customer has disabled this import source, so data can't be imported)
  • MISSING_MAPPING (no object schema and mapping configuration has been submitted yet, so data can't be imported)

Step 3: Submit schema and mapping configuration

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
2
PUT 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.

Step 4: Kick off an import

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
2
POST 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:

  • Submit data generation progress reports to Assets (submitProgress)
  • Submit actual data sets to Assets (submitResults)
  • Query the status of this import execution (getExecutionStatus)
  • Cancel the import execution (cancel)

Step 5: Submit data sets and report progress

Report progress

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
2
PUT 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.

Submit data sets

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.

Submitting a data chunk

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

Signalling data completion

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.

Chunk data structure

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.

Cancelling imports

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
2
DELETE 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: