Web Service Import Sets
| Note: This article applies to Fuji and earlier releases. For more current information, see Web Service Import Sets at http://docs.servicenow.com
The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.
- 1 Overview
- 2 Security Requirements
- 3 Import Set Mode
- 4 Editing a Web Service
- 5 Creating a New Web Service
- 6 Mapping
- 7 Inserting Multiple Records
- 8 Administration
- 9 Debugging
- 10 Enhancements
Web service import sets provides a web service interface for import set tables. By default, this type of web service will transform the incoming data synchronously based on the associated transform maps. If the associated import set mode is set to Asynchronous, the behavior is to save the data for transformation at a later time. Web service import sets tables publish all the default web service functions in the WSDL.
This plugin also provides these standard import set tables:
- Computer [imp_computer]
- Location [imp_location]
- Notification [imp_notification]
- User [imp_user]
You can access web service import set WSDLs by adding .do?WSDL to the import set table URL. For example:
2 Security Requirements
- Basic authentication requires a web service user provide a valid user name and password
- Contextual security requires a web service user meet the queried table's access control rules
Certain roles are required for using web service import sets.
|import_set_loader||Allows users to load import sets.|
|import_scheduler||Allows users to scheduled imports.|
|import_transformer||Allows users to manage import set transform maps and run transforms.|
|import_admin||Allows users to manage all aspects of import sets and imports.|
If your instance uses high security settings, the web service user may also need the soap role.
3 Import Set Mode
When a web service message inserts a record into an import set table, and the table did not previously have an import set referenced, a new one will be created, and its Mode will be set as Synchronous. A synchronous import set transforms 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, the state of all synchronous import sets is automatically set to Processed at midnight. As a result, when a new insert happens to the same table, a new synchronous import set will be created.
Changing this import set to a Mode of Asynchronous and a State of Loading prevents the data from being transformed immediately. Using this configuration, the import set is loaded but not transformed. You can then perform the transformation manually or with a scheduled script job.
|Asynchronous||Loading||Data transformation does not occur automatically. Data added to import set row has a State of Pending. Data transformation can be scheduled or performed manually after the state changes 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 occurs 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 with a Mode of Synchronous and State of Loading is created. Changing the state to Loaded indicates that a new synchronous import set should be created for the next import set row insert and transformed immediately.|
3.1 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, starting with the Fuji release, Eureka Patch 7, and Dublin Patch 7.
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. This property is true by default for instances that upgrade to one of these releases, false for new instances starting with one of these releases.
The system property glide.soap.import_set_insert_serialized.<table name>, 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.
|Note: Disabling serialization can result in the creation of duplicate records when a coalesce field is defined for a target table transform map.|
See Available System Properties for detailed information about these properties.
3.2 Controlling Maximum Request Body Size
You can limit the maximum size allowed in a request body. By default, the maximum size allowed is 70MB. This maximum size applies to all SOAP requests, but usually only insert or insertMultiple operations reach this limit.
To change the maximum request body size, navigate to System Web Services > Properties and change the value of the Maximum total size allowed in the SOAP request body, in MB property. Specify a value of -1 for no limit.
|Note: Setting the maximum higher than 70MB can cause the instance to run out of memory during very large imports.|
3.3 Controlling insertMultiple WSDL Format
When inserting records using SOAP web service import sets, the instance generates a WSDL that describes the inserted records. The property glide.wsdl.consistent_insert_multiple controls the format of the WSDL used by the insertMultiple operation, starting with the Fuji release. When enabled, this property causes the insertMultiple WSDL format to be consistent with the SOAP response and with other web service import set WSDLs. Prior to Fuji, the insertMultiple WSDL format is not consistent with the SOAP response. Enable this property when using insertMultiple if there is more than one transform map on the import set table.
If you activate the Insert Multiple Web Services plugin after upgrading to Fuji, this property is enabled by default. For instances using insertMultiple prior to Fuji, to enable the consistent WSDL format, navigate to System Web Services > Properties and select the Make insertMultiple WSDLs consistent property. See the web service import set WSDL examples for more information.
3.4 Standard Web Service Response
Inserting a record using a web service import set causes the instance to respond with information about the inserted record.
The response from a web service import set insert call returns the following response, depending on protocol.
<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>
3.4.1 Returned Values
The web service response returns the following field values, depending on the protocol used.
|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 such as 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 is 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.|
3.5 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.
4 Editing a Web Service
Clicking on any of the web service import sets modules opens a form that allows you to edit the web service. You can also access this form using the Edit Web Service related link from any import set table list.
The Name of the web service is the table name of the import set table, which also appears in the WSDL field to display the URL to access the WSDL definition for the web service.
4.1 Web Service Fields
The Web Service Fields related list displays the fields available for this web service. All fields by default are published as the XSD type of xsd:string. The Name is the field that is exposed for the web service and therefore appears as the name of the field in the WSDL. The Label is the label of the field as it appears for the Import Sets.
You can add, delete or modify web service fields from this list.
|Note: After modifying the list of web service fields, click Update to save the changes.|
4.2 Web Service Transform Map
These are the transform maps associated with this web service. When the import set mode is Synchronous, the input data will be transformed immediately.
5 Creating a New Web Service
Navigate to System Web Services > Create New.
The Name of the web service is the table name of the import set table whereas the Label field is the resulting table field.
If you want to create a transform map after creating the web service, check the Create transform map checkbox and choose the target table you want the data to transform into. After the Create button is clicked, the web service will be created and you will be immediately put into the Table Transform Map form. You may then continue to specify the transform map or script.
5.1 Web Service Fields
The fields available for this web service. All fields by default are published as the XSD type of xsd:string. The Name is the field that is exposed for the web service and therefore appears as the name of the field in the WSDL. The Label is the label of the field as it appears for the import sets table.
You can Add, mark for Delete or modify (double click on the field) an existing web service field in this list.
|Note: After adding web service fields, click Create to create the web service import set table.|
To add other fields after the Web Service is created, find the target table, and add the fields to that table.
During the creation of the web service import set, you can create the transform map for it. All transform maps will be run for the service when it is invoked if the import set mode is set as Synchronous.
The following image is an example of the transform map associated with the notification web service import set.
6.1 Adding Web Service Response Values
In the transform map script associated with a web service import set, setting certain variable values has the effect of changing the response values of the web service. In addition to the normal variables that are available in a transform map script, the response object holds dynamically created response elements. You can use this object to customize the response of a web service import set insert.
For example, the following code snippet inserts the transaction_id and hello variables into the response.
// create new elements called "transaction_id" // and "hello" in the web service response response.transaction_id = "abc123"; response.hello = "world"; status_message="message 1"; // this is the normal status_message variable
This code snippet results in the following response being sent back to the web service consumer, depending on the protocol.
<soapenv:Envelope xmlns:imp="http://www.service-now.com/imp_notification" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header/> <soapenv:Body> <insertResponse xmlns="http://www.service-now.com/imp_notification"> <sys_id>969d157c0a0a0baf008ba5770ffa798c</sys_id> <table>incident</table> <display_name>number</display_name> <display_value>INC0010091</display_value> <status>inserted</status> <status_message>message 1</status_message> <transaction_id>abc123</transaction_id> <hello>world</hello> </insertResponse> </soapenv:Body> </soapenv:Envelope>
7 Inserting Multiple Records
You can insert multiple records in one SOAP request by using the insertMultiple operation. The insertMultiple operation is available for the Direct Web Service API and Web Service Import Sets. To enable insertMultiple, activate the Insert Multiple Web Service plugin.
|Click the plus to expand instructions for activating a plugin.|
If you have the admin role, use the following steps to activate the plugin.
|Note: Activating this plugin adds a new operation to the WSDL. After this plugin is activated, consume a new WSDL to update your web services client.|
When displaying a mapped web service table, the following related links are available.
- Import Sets: the import sets related to this web service import set
- Transform Maps: a list of transform maps related to this web service
- Transform History: the transformation history
- Edit Web Service: edit the web service
The following image shows a record that was inserted into the web service import set Notification. The target record is the resulting creation or modification to the Incident table record as a result of the transform.
To debug incoming SOAP requests, you must add a system property.
|glide.processor.debug.SOAPProcessor|| Controls if the system logs all incoming SOAP requests. To prevent the system logs from growing unnecessarily, set this property to false when you finish debugging incoming web service requests.
- You can control the WSDL format for the insertMultiple operation.
- You can specify the maximum body size for inbound SOAP requests.
- Insert operations to a given target table are performed concurrently for optimal performance when an import set has no coalesce field. The properties glide.import_set_insert_serialized_when_no_coalesce and glide.import_set_insert_serialized.<table_name> control how the instance inserts records from web service calls into an import set table.