Web service import set mode
Summarize
Summary of Web Service Import Set Mode
This document details the functionality and behavior of the Web Service Import Set mode in ServiceNow, particularly focusing on the Synchronous and Asynchronous modes. It explains how records are inserted into import set tables via SOAP messages and the implications of each mode on data transformation and handling.
Show less
Key Features
- Synchronous Mode: Automatically transforms data as soon as it is inserted into the import set, with a default state of Loading. At midnight, these records transition to Processed state.
- Asynchronous Mode: Defers data transformation to a later time, either manually or through a scheduled job. Data is first loaded into the import set with a Pending state.
- Coalesce Fields: Control duplicate records during transformation. If coalesce fields are defined, transformations occur serially; if not, they occur concurrently.
- SOAP Response: Contains standard fields such as sysid, table name, displayname, displayvalue, status, and optional error messages, providing essential feedback about the web service call.
Key Outcomes
By understanding and utilizing the Web Service Import Set mode, customers can effectively manage how data is imported and transformed in ServiceNow, ensuring data integrity and optimizing performance. Adjusting import set modes allows for better control over record handling and transformation processes, leading to improved system efficiency.
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.