Import Set API
-
- UpdatedAug 1, 2024
- 8 minutes to read
- Xanadu
- API reference
The Import Set API provides endpoints that allow you to interact with import set tables.
This API transforms incoming data based on associated transform maps. The import set API supports synchronous transforms. The Import Set API mirrors the existing SOAP interface.
Security
Access to tables via the REST API is restricted by BasicAuth. To allow access to tables without any authentication or authorization, add the table name to sys_public.list. ACLs defined on tables are still enforced, and it is the administrator's responsibility to deactivate ACLs.
Import Set - GET /now/import/{stagingTableName}/{sys_id}
Retrieves the specified import staging record and resulting transformation result.
URL format
Versioned URL: /api/now/{api_version}/import/{stagingTableName}/{sys_id}
Default URL: /api/now/import/{stagingTableName}/{sys_id}
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the
endpoint to access. For example, v1 or
v2. Only specify this value to use an endpoint version
other than the latest.
Data type: String |
stagingTableName | Name of the table from which to obtain the import data. Data type: String |
sys_id | Sys_id of the record that contains the data. Data type: String |
Name | Description |
---|---|
None |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
Example: Sample cURL request
Import Set - POST /now/import/{stagingTableName}
Inserts incoming data into a specified staging table and triggers transformation based on predefined transform maps in the import set table.
URL format
Versioned URL: /api/now/{api_version}/import/{stagingTableName}
Default URL: /api/now/import/{stagingTableName}
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the
endpoint to access. For example, v1 or
v2. Only specify this value to use an endpoint version
other than the latest.
Data type: String |
stagingTableName | Name of the table from which to import the data. Data type: String |
Name | Description |
---|---|
None |
Name | Description |
---|---|
Call specific | Name-value pairs to insert in the import fields. Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
Content-Type | Data format of the
request body. Supported types: application/json or
application/xml.
Default: application/json |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
Example: Sample cURL request
Import Set - POST /now/import/{stagingTableName}/insertMultiple
Inserts multiple records into a specified staging table and triggers transformation based on predefined transform maps or Robust Transform Engine (RTE) configurations in a single request.
Transformation is asynchronous by default. To set synchronous transformation, create a new record in the Rest Insert Multiples [sys_rest_insert_multiple] table, select the source table, and set the transformation to synchronous.
- Data source file format
- If you generate a staging table from a JSON data source, match the JSON format of the source file.
- Staging table column format
- Default. Matches the staging table column request body format in key value pairs.
URL format
Versioned URL: /api/now/{api_version}/import/{stagingTableName}/insertMultiple
Default URL: /api/now/import/{stagingTableName}/insertMultiple
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the
endpoint to access. For example, v1 or
v2. Only specify this value to use an endpoint version
other than the latest.
Data type: String |
stagingTableName | Name of the import set table from which to import the data. Refer to Import sets key concepts. Data type: String |
Name | Description |
---|---|
multi_import_set_id | Sys_id of an entry in the Multi Import Sets [sys_multi_import_set] table. If
specified, adds the current import to this multiple import set instead of adding to
a new multiple import set. Data type: String |
run_after | Sys_id of an entry in the Import Sets [sys_import_set] table. Enables running
the current import set after the specified import set is complete. You can use this
parameter to enforce the sequential order of imports. This parameter is only valid in asynchronous transformations. Data type: String |
Format | Description |
---|---|
Data source file | This request body format matches the JSON file format used to create the data
source. Provide the request body in the same format as the JSON in the data source.
JSON input varies depending on the properties in your data source. Refer to JSON
information in File type data source.
Data type: Object |
Staging table column (default) | This request body format matches staging table columns. Use the records array of key-value pairs matching the staging table column to insert in the import fields. Each JSON key is maps the table
column to a JSON value representing the value to be inserted. JSON input varies depending on what fields are in your staging table. The column mapping default key value is to the column table. You can modify mapping settings by adding an entry in the Rest Insert Multiples [sys_rest_insert_multiple] table and changing the Column mapping from Label to
Column name.
The Data dictionary tables provides details on table fields in the system. Data type: Array |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response body. Only supports application/json. |
Content-Type | Data format of the request body. Only supports application/json. |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body (JSON)
Name | Description |
---|---|
import_set_id | Sys_id of the record added to the Import Sets [sys_import_set] table. For
asynchronous requests, you can use this value to run another import set after this
import set process is complete. Data type: String |
multi_import_set_id | Sys_id of the record added to the Multi Import Sets [sys_multi_import_set]
table. This value can be used to group multiple import sets into one set. Data type: String |
Example: Sample cURL request
The following example shows how to run a transform on an import table called u_employee_import_set_table using the staging table column format.
Results include sys_ids for new records in the Import Sets [sys_import_set] and Multi Import Sets [sys_multi_import_set] tables.