REST API for data imports

You use the GET operation on the api/import_status.json element to start the import of data or check its status.

Resource URL

To start the import or retrieve information about its status, use the following URL:
https://hostname:port/api/import_status.json

Resource information

Table 1. Resource information
Operation details Description
Purpose Starts the import or returns its status.
HTTP method GET
Resource URI https://server_host_name:port_number/api/import_status.json
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request payload n/a
Request Content-Type
  • application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Response payload Import status element
Response Content-Type
  • application/json
Normal HTTP response codes
  • 200 – OK
Error HTTP response codes
  • 500 – “Bad Request” if a query parameter contains errors or is missing

Message body includes an error message with details.

Available columns

Table 2. Available columns
Column Description Displayed by default Type
mode Status of the data import. Possible values:
  • none - data import has never been initiated
  • idle - no data imports are currently running
  • running - a data import is in progress
  • pending - an action performed in the user interface requires a data import to be started for the change to take effect
String
can_run_imports Specifies whether the user can run imports. Boolean
import_status_url Web address of this API. String
import_create_url Web address of the data imports panel in License Metric Tool. String
progress Percentage status of the running import. Integer
last_success_time Date and time of the last successful import. String
last_import_type Type of the last import. Possible values:
  • complete
  • partial
String
last_status Status of the last import. String
last_import_time Date and time of the last import. String
next_import_time Date and time of the next scheduled import. String
next_import_time_in Time to the next import provided in seconds. Integer
next_import_type Type of the next scheduled import. Possible values:
  • complete
  • partial
String

Query parameters

Table 3. Query parameters for running the import
Parameter Description Required Value
run Specifies that the import should be started.
URL?run=true
No true

Example HTTP conversation - starting the import

Request
GET https://server_host_name:port_number/api/import_status.json?run=true
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response header
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
Response body (JSON)
If a data import was successfully started:
{
"mode":"running",
"can_run_imports":true,
"import_status_url":"/import_status",
"import_create_url":"/management/imports",
"progress":1,
"last_success_time":"2022-08-30T03:09:04Z",
"last_status":"successful",
"last_import_time":"2022-08-30T03:09:04Z",
"last_import_type":"complete",
"next_import_time":"2022-08-31T00:00:00Z",
"next_import_time_in":38946,
"next_import_type":"complete"
}

Example HTTP conversation - checking the status of the import

Request
GET https://server_host_name:port_number/api/import_status.json
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response header
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
Response body (JSON)
If a data import has never been initiated:
{ 
 "mode": "none",
 "can_run_imports": true,
 "import_status_url": "/import_status",
 "import_create_url": "/management/imports",
 "progress": 59
 ...
 }
If a data import is in progress:
{ 
 "mode": "running",
 "can_run_imports": true,
 "import_status_url": "/import_status",
 "import_create_url": "/management/imports",
 "progress": 59
 ...
 }
If a data import is not running:
{
  "mode": "idle"/"pending",
  "can_run_imports": true,
  "import_status_url": "/import_status",
  "import_create_url": "/management/imports",
  "last_status": successful,
  "last_success_time": "2014-06-18T04:00:29Z"
  ... 
}