Web service import set mode
Summarize
Summary of Web service import set mode
This document explains how ServiceNow handles import sets created via SOAP web service messages. When a SOAP message inserts data into an import set table without an existing import set in the Loading state, a new import set is created inSynchronousmode with a default state of Loading. In Synchronous mode, data transformation occurs immediately upon insertion if a transform map exists. By default, these import sets are automatically changed to Processed at midnight, causing a new Synchronous import set to be created for subsequent inserts.
Show less
Changing the import set mode to Asynchronous with a Loading state defers transformation, allowing data to be loaded first and transformed later, either manually or via scheduled jobs.
Import Set Modes and States
| Mode | State | Function |
|---|---|---|
| Asynchronous | Loading | Data is loaded without immediate transformation. Rows have a Pending state. Transformation can be scheduled or manual when state changes to Loaded. |
| Asynchronous | Loaded | Indicates loading is complete; data transformation can now occur manually or via scheduling. |
| Synchronous | Loading | Data transformation happens automatically and immediately upon row insertion. |
| Synchronous | Loaded | Signals that new Synchronous import sets should be created for new inserts and transformed immediately. |
Controlling Insert Behavior
For import sets with coalesce fields, records are transformed serially to prevent duplicates. Without coalesce fields, transformation occurs concurrently. The system property glide.importsetinsertserializedwhennocoalesce controls this behavior.
Additionally, the glide.importsetinsertserialized.<table name> property can be used per import set table to serialize database inserts and prevent duplicates from simultaneous web service calls. Setting this property to false on tables without coalesce fields can improve performance but risks duplicate records.
Note that glide.importsetinsertserialized.<table name> supersedes the older glide.soap.importsetinsertserialized.<table name> property if both are defined.
Standard SOAP Response
When a web service import set insert is called, the SOAP response includes key fields:
- sysid: The unique identifier of the created or modified record.
- table: The table affected; for asynchronous calls, this is the import set table.
- displayname: The display field name for the record.
- displayvalue: The value of the display field (e.g., incident number).
- status: Indicates the action taken, such as inserted, updated, ignored, skipped, or error.
- statusmessage: Optional message explaining the status, often derived from the import set row's Comment field.
- errormessage: Optional message providing details if an error occurred.
Customizing the SOAP Response
The SOAP response can be tailored by overriding the statusmessage in the transform script to include additional information beyond the WSDL defaults.
When a SOAP message inserts a record into an import set table, and there is no import set for that table in the Loading state, a new import set will be created with the Mode set to Synchronous.
An import set with a Mode of Synchronous will transform the data as soon as it is inserted (provided that the transform map already exists). This import set will also have a default State of Loading. By default, all Synchronous import sets will automatically be modified to Processed at midnight. As a result, when a new insert happens to the same table, a new Synchronous import set will be created.
| Mode | State | Function |
|---|---|---|
| Asynchronous | Loading | Data transformation is not occurring automatically and immediately. Data added to import set row has a state of "Pending". Transform can be scheduled or executed manually when state is changed to Loaded |
| Asynchronous | Loaded | Marks the completion of data loading. Data transformation can now occur in a scheduled fashion or manually. |
| Synchronous | Loading | Data transformation is occurring automatically and immediately whenever data is inserted into the associated import set row. |
| Synchronous | Loaded | When new data is inserted into this associated import set, a new import set of mode Synchronous and state Loading will be created. Changing the state to Loaded is a way to indicate that a new Synchronous import set should be created for the next import set row insert (and transformed immediately) |
Controlling Insert Behavior
In imports sets that specify one or more coalesce fields, records with a matching coalesce value are transformed from source to target table serially (one at a time) to prevent duplicates.
In import sets that do not specify any coalesce field, records are transformed concurrently. You can control this behavior using the glide.import_set_insert_serialized_when_no_coalesce property.
The glide.import_set_insert_serialized.<table name> system property controls how the instance inserts records from web service calls into a specific import set table. When true, this property prevents identical simultaneous inserts from creating duplicate records by serializing the database insert operations. If a target table does not have any coalesce fields defined in a transform map, set this property to false to improve web service import set performance.
Standard SOAP Response
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><insertResponse><sys_id>fa648f5f0a0a0b2b0048e7012448b8f1</sys_id><table>incident</table><display_name>number</display_name><display_value>INC10014</display_value><status>inserted</status></insertResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>| Field | Description |
|---|---|
| sys_id | The Sys_id of the resulting record that was created or modified |
| table | The table name of the table that was affected. In the case of an Asynchronous call, the table name would be the import set table eg. imp_notification for the Notifications web service import set table |
| display_name | The name of the field that is set as the display field for the record that was created or modified |
| display_value | The value of the field designated as the display field. For example, the display field for the Incident table is the Number field and an example value would be INC10001 |
| status | A string value that indicates the action that occurred as a result of the web
service invocation, relating to the record defined by the sys_id
and table field values
|
| status_message | This value translates to the value found in the Comment field of the import set row and usually contains information related to the status value eg. "No field values changed" when the status is "ignored' . Setting this value to a customized string value will cause the SOAP response to contain an optional status_message field to be returned. |
| error_message | The message related to a status of error. When an error occurs, setting this value to a customized string value will cause the SOAP response to contain an optional error_message field to be returned |
Tailoring the SOAP Response
It is possible to include information other than the information specified in the WSDL by overwriting the contents of status_message using the transform script.