Loading

Web Service Import Sets

From ServiceNow Wiki
Home > Administer > Managing Data > Import Sets > Web Service Import Sets
Jump to: navigation, search
Web Services

Contents

1 Overview

Workflow for Web Service import sets

Web Service Import Sets complement Direct Web Services and Scripted Web Services in providing a web service interface to Import Set tables. This type of web service will transform the incoming data synchronously based on the associated transform maps by default. 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 the following standard import set tables:

  • Computer
  • Location
  • Notification
  • User

Web service import set WSDL are accessed by specifying the import set table name + ".do?WSDL" on the URL. For example:

http://<instance name>.service-now.com/imp_notification.do?WSDL (The System Web Service plugin must be enabled first)

2 Security Requirements

Web Service Import Sets use the same security mechanisms as SOAP Web Services:

  • 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

If your instance uses high security settings, the Web Service user may also need the soap role.

3 Import Set Mode

When a SOAP 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. 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.

Import set record

Changing this import set to a mode of Asynchronous and a state of Loading has the effect of not transforming the incoming data as it is inserted, but rather "loading" the import set and deferring the data transformation later, either manually, or with a scheduled script job.

Mode State Function
Asynchronous Loading Data transformation is not occuring 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)

3.1 Controlling Insert Behavior

The system property glide.soap.import_set_insert_serialized.<table name>, controls how the instance inserts records from web service calls into an import set table (Calgary). In previous releases, it was possible for a multi-threaded Web Services client to send identical insert requests to the same table at the same time. In some cases, the simultaneous identical requests could produce duplicate records. The system property's default value (true) prevents identical simultaneous inserts from creating duplicate records.

Note
Note: Setting this property to false can result in the creation of duplicate records.


Property Description
glide.soap.import_set_insert_serialized.<table name> Controls the processing of web service inserts. When this property is set to true, the instance processes multiple simultaneous inserts one at a time (serially across nodes) to ensure an accurate transform. Serialized processing slows down the speed at which the instance processes inserts. When this property is set to false, multiple simultaneous inserts into an import set table result in simultaneous transforms that may produce duplicate target records due to the coalesce value being created at the same time.

Tip: Only set this value to false to optimize for performance when the related transform map does not have a coalesce value that may be present simultaneously.

  • Type: true | false
  • Default value: true
  • Location: Add to the System Properties [sys_properties] table

3.2 Standard SOAP Response

The SOAP response from a web service import set insert call returns the following standard values

<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 occured 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.3 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 module will take you to a form that edits the web service. You will also arrive at the same form through a related link called Edit Web Service of 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 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, mark for Delete or modify (double click on the field) an existing web service field in this list.

Note
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
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 may optionally create the transform map for it. All transform maps will be executed for the service when it is invoked if the import set mode is set as "Synchronous" (the default).

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 have 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 table below documents the variables that are available and their effects.

Variable name Type Description Usage Example
response Output Object

"response" is a Javascript object that holds dynamically created response elements used to customize the output response of a web service import set insert.

// 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

The code snippet above results in the following response being generated back to the web service consumer

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

Note
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, you will have the following related links:

  • 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

If you need to debug a SOAP Request coming into the system, you can create a System Property and name it glide.processor.debug.SOAPProcessor.

Once you have created it, set it to true to have all SOAP requests be logged in the System Log. Set it to false when you are done so as to keep the size of your System Log to a managed length.

10 Examples

10.1 Sample WSDL

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://www.service-now.com" 
 xmlns:tns="http://www.service-now.com/imp_notification" 
 xmlns:sncns="http://www.service-now.com" 
 xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
 xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:types>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     elementFormDefault="unqualified" 
     targetNamespace="http://www.service-now.com/imp_notification">
      <xsd:element name="insert">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="0" name="corrective_message" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="duration" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="expires_on" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="message" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="severity" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="source" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="timestamp" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="0" name="type" type="xsd:string"/>
            <xsd:element maxOccurs="1" minOccurs="1" name="uuid" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    <xsd:element name="insertResponse">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element maxOccurs="1" minOccurs="1" name="sys_id" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="1" name="table" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="1" name="display_name" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="1" name="display_value" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="1" name="status" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="0" name="status_message" type="xsd:string"/>
          <xsd:element maxOccurs="1" minOccurs="0" name="error_message" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  </wsdl:types>
  <wsdl:message name="insertSoapOut">
    <wsdl:part name="imp_notification" element="tns:insertResponse"/>
  </wsdl:message>
  <wsdl:message name="insertSoapIn">
    <wsdl:part name="imp_notification" element="tns:insert"/>
  </wsdl:message>
  <wsdl:portType name="ServiceNowSoap">
    <wsdl:operation name="insert">
      <wsdl:input message="sncns:insertSoapIn"/>
      <wsdl:output message="sncns:insertSoapOut"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="ServiceNowSoap" type="sncns:ServiceNowSoap">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="insert">
      <soap:operation soapAction="http://www.service-now.com/imp_notification/insert" style="document"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="ServiceNow">
    <wsdl:port name="ServiceNowSoap" binding="sncns:ServiceNowSoap">
      <soap:address location="http://Macintosh-7.local:8080/glide/imp_notification.do?SOAP"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

10.2 Sample SOAP Envelope

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
     <insert xmlns="http://www.service-now.com">
       <message xsi:type="xsd:string">Host 198.10.10.210 is down</message>
       <uuid xsi:type="xsd:string">HGAF76251HGF1</uuid>
     </insert>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.3 Sample SOAP Response

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
 SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>     
    <insertResponse>
      <sys_id>b54aafbfc0a8006f0058db95daa5b88d</sys_id>
      <table>incident</table>
      <display_name>number</display_name>
      <display_value>INC10008</display_value>
      <status>ignored</status>
      <status_message>No field values changed</status_message>
    </insertResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.4 Example Invocation using Perl

The following example script will use the Notification web service to create an Incident as the itil user. It uses the Perl language and the SOAP::Lite package.

#!/usr/bin/perl -w
 
#use SOAP::Lite ( +trace => all, maptype => {} );
use SOAP::Lite;
 
sub SOAP::Transport::HTTP::Client::get_basic_credentials {
   return 'itil' =>'itil'; // set basic auth credentials for the itil user
}
 
my $soap = SOAP::Lite
    ->proxy('http://localhost:8080/glide/imp_notification.do?SOAP');
 
my $method = SOAP::Data->name('insert')
    ->;attr({xmlns => 'http://www.service-now.com/'});
 
# insert into the web service
my @params = ( SOAP::Data->name(message => 'problem detected for database DB12DG') );
push(@params, SOAP::Data->name(source =>'DB12DG') );
push(@params, SOAP::Data->name(uuid =>'HGAF76251HGF2') );
 
my $result = $soap->call($method =>@params);
 
print_fault($result); // print any SOAP faults
print_result($result); // print any results
 
sub print_result {
  my ($result) = @_;
  if ($result->body && $result->body->{'insertResponse'}) {
    my %keyHash = %{ $result->body->{'insertResponse'} };
    foreach my $k (keys %keyHash) {
        print "name=$k   value=$keyHash{$k}\n";
    }
  }
}
 
sub print_fault {
  my ($result) = @_;
  if ($result->fault) {
    print "faultcode=" . $result->fault->{'faultcode'} . "\n";
    print "faultstring=" . $result->fault->{'faultstring'} . "\n";
    print "detail=" . $result->fault->{'detail'} . "\n";
  }
}

The following is the result printed out by the Perl script on the console

name=display_value   value=INC10011
name=status   value=inserted
name=table   value=incident
name=display_name   value=number
name=sys_id   value=cd45649c0a0a0b2b00e6f27649d6bd2c

The following image shows the resultant row created for the import set table Notification (imp_notification).

Sample row created from an import set

11 Enhancements

11.1 Calgary

The following enhancement is available as of the Calgary release.

  • A new system property, glide.soap.import_set_insert_serialized.<table name>, controls 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
Views
Personal tools