Web Service Import Sets

From ServiceNow Wiki
Home > Administer > Managing Data > Import Sets > Web Service Import Sets
Jump to: navigation, search
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.

Web Services

1 Overview

Workflow for Web Service import sets

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.

System Web Services

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:

http://<instance name>.service-now.com/imp_notification.do?WSDL

2 Security Requirements

Web service import sets use the same security mechanisms as SOAP web services or RESTful web services, depending on which protocol you use:

  • 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

2.1 Roles

Certain roles are required for using web service import sets.

Role Description
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.

Import set record

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.

Mode State Function
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.

The property glide.import_set_insert_serialized.<table name> provides the same functionality, starting with the Fuji release, Eureka Patch 7, and Dublin Patch 7.

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 Response

3.4.1 Returned Values

The web service response returns the following field values, depending on the protocol used.

SOAP 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 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.
  • inserted - the record was inserted
  • updated - the record was updated
  • ignored - the input was ignored, the record was not updated and no new record was created
  • skipped - the input data was skipped (similar to ignored) due to missing coalesce values
  • error - there was an error processing the input
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.

Editing Web Service

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.

Creating a new Web Service

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.

6 Mapping

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.

SOAP transform map

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" 
      <insertResponse xmlns="http://www.service-now.com/imp_notification">
         <status_message>message 1</status_message>

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.

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.

8 Administration

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.

SOAP notification

9 Debugging

To debug incoming SOAP requests, you must add a system property.

Property Description
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.
  • Type: true | false
  • Default value: false
  • Location: Add to the System Property [sys_properties] table

10 Enhancements

10.1 Fuji

  • 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.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance