Sample Custom Incident SOAP Interface

General Add comments
by:

This article describes a sample setup of an Incident interface using the SOAP protocol between ServiceNow and an external system. It aims to deliver an interface that can easily be monitored by any user with access to the Incident Management module and it will also hand you some important considerations to take into account while designing the interface.

Functional Setup

We are looking at a situation where two systems interface Incidents. Both systems will play a role in the Incident Management process, which means that inserts and updates can be created on either side. Goals of an interface should be:

  • The Incident Process on both sides must be supported
  • Minimum manual work
  • The Incident Process on both sides should be respected. This means that expecting once side to change its process to support the process on the other side should be prevented. This also goes for Codings such as Status and Categorization
  • Data consistency must be preserved: at each moment the data in both systems must match
  • It must be possible to monitor the interface

Questions

The first step in creating an interface is to look at the process on both sides and to find a logical flow across both systems. Main questions will be:

  1. What do we do with the Status?
    • Do we keep them matched? (for instance: “New” in one system matches “Created” in the other)
    • Does the status reflect the cross-system flow? (for instance: “Active” in one system matches “Awaiting 3rd party” in the other)
  2. What do we do with Assignment?
    • Do we keep them matched? (this would mean that all assignment groups need to exist in both systems)
    • Do we regard the other system as a party / assignment group? (This would mean that we “assign” a ticket to a certain group and thus trigger the transfer of the incident ownership to the other system)
  3. What do we do with Closure?
    • Can any system close an Incident? (make sure the logic in both systems matches: Closed Incidents cannot be reopened for instance)
    • Can only the source system close an Incident?
  4. Which information (attributes) is needed on each side?
  5. How do the attributes from one side map to the attributes on the other side?
  6. What type of Error Handling should be set up?
    • There are two levels of Errors: Technical and Functional
    • The Synchronous response will indicate any Technical Errors
    • Functional Errors can be reported at two levels:
      • In the Synchronous Response
      • In a separate Asynchronous Response

Recommendations

  1. Translation is done in the receiving system, and use defaults for unknown values. This way data modifications in one system do not require the simultaneous update of the other system. Failing to take this step will result in complex cross-system change procedures
  2. Once a link is established, ALL updates should be corresponded to the other system. This way both systems will remain consistent.
  3. An error handling procedure should be established. This is needed to discover any mismatches at an early stage, and consistency is guaranteed. Failing to do so may result in each system expecting action form users in the other system.
  4. Every message should result in an Insert/Update or in an Error.
    • Synchronous Response should always be sent. Not receiving a Synchronous response should trigger some sort of Time Out processing. Synchronous responses can be used to:
      • Return Technical Errors (for instance incorrect XML layout, Missing attributes)
      • Return Functional Errors (for instance incorrect data)
      • Return Functional Confirmations
    • Asynchronous Response may be used for both confirmations and errors if it was decided to use them. Asynchronous responses can be used to
      • Return Functional Errors (for instance incorrect data)
      • Return Functional Confirmations
  • A separate table containing both the inbound and the outbound traffic should be created. This table contains a link to the Incident involved so it can be added as a related list to the Incidents. This way it is very easy to track any messages that were sent / received on behalf of this incident and both issues and data are available to the Incident user.

Technical Setup

In the Technical part I will describe the data and processing flow which can be used regardless of some decisions that need to be made.

  1. The External system sends a SOAP message to our Web Service
  2. The Web Service receives the system and transfers it to the correct processing logic
  3. The processing can be done in two ways: Via Inbound Web Services (which is the easiest option. Service Now determines the WSDL in this case) or Scripted Web Services (which is a more complex way, but this may be needed if the receiving party cannot handle the ServiceNow WSDL).
    • A. The Scripted Web Service will receive the XML message and process it. The result of this processing are a Synchronous Response and a Message that will be stored in the Message Table
    • B. The Transform Map will process the message. The results here are a Synchronous Response and a Message that will be stored in the Message Table
  4. The Message Table is an table that stores all messages From this table inbound messages are processed to update Incidents, but also outbound messages are stored to be sent. This table should contain the following information:
    • A. Message ID (this should be unique and created by the sending system)
    • B. Direction (inbound for received messages or outbound for sent messages)
    • C. (Optional) Transaction ID: this is needed if you work with an Asynchronous response. The Asynchronous response should send a message back containing the same Transaction ID
    • D. Incident ID of the sending system
    • E. Incident ID (if available) of the receiving system
    • F. Message Processing Status
    • J. (Optional) Any Message Processing Error
    • H. All relevant data
    • I. The XML Message that was sent / received
    • J. A link to the ServiceNow Incident
    • K. (Optional) the system to interface with
  5. This Business Rule (on the Message Table) will pick up any inbound messages and insert / update the inbound messages accordingly. If you make use of an Asynchronous response, this Business Rule will also create the Response (which again should be a record in the Message Table)
  6. The Incident Table speaks for itself. In the Incident Form it is recommended to add a related list showing all related records in the Message Table.
  7. A Business Rule (on the Incident Table) will check after each Incident Insert / Update if the new information needs to be shared with an external system. If so, a Message Record is created in the Message Table
  8. A Business Rule (on the Message Table) will check if there are any Messages that need to be sent out. If so, if will create and send the message, and process the Synchronous response that comes back.
  9. The SOAP Message is the SOAP Definition that is created using the WSDL from the external system.  This definition is used to create a template for the SOAP message. The Business Rule (8) needs this template to send out the messages.
  10. Obviously you need somebody to talk to. The External System will send back a Synchronous Response. Asynchronous Messages are treated like any other message, except for the way the processing takes place: It is less likely that the incident itself gets updated, but the originating messages can be.

Considerations

  1. Inbound Translations can be done at Scripted Web Services (3a), Transform Map (3b) or the Inbound Business Rule (5).
    • A. Doing it at 3a and 3b is usually easier
    • B. Doing it at 5 makes sure that you have better visibility in the Message Table (4)
  2. Next to the Business Rule (8) responsible for Sending, it is an option to also create a Scheduled Job that automatically resends messages that enter a TimeOut state. This state typically happens when a Synchronous Response doesn’t come back within a certain amount of time (default 5 minutes).

Code Samples

Some code bits related to the messages are useful in this interface. Below an overview:

3a – Scripted Web Services
[cc lang=”javascript”]
// The parameter that contains the received XML:
var xml = new XMLDocument(soapRequestXML);

// Send back a response:
var r = new XMLDocument(“”);
r.setCurrent(r.createElement(“IncidentResponse”));
r.createElement(“success”, “true”);
r.createElement(“processingstate”,”incident inserted in ServiceNow”);
response.soapResponseElement = r.getDocumentElement();
[/cc]

3b – Transform Maps
[cc lang=”javascript”]
// Add a new element to the response (do this in the main script in the Transform Map):
response.success = “true”;
response.processingstate = “incident inserted in ServiceNow”;

// Retrieve data from an attribute (in the main script in the Transform Map.
// Obviously you can also do this in the Field Mapping).
target.description = source.description;
[/cc]

8 – Business Rule
[cc lang=”javascript”]
// Create a SOAP message (defined in the SOAP Message module) and send it
var soapMsg = “Incident Message” // this is the name of a SOAP Message Definition
var soapAct = “sendinsert”; // action that is defined in the SOAP Message definition
var s = new SOAPMessage(soapMsg, soapAct);
s.setParameter(“transactiontype”, “create”);
var response = s.post();

// retrieve the (synchronous) response as XML:
var xmlResponse = new XMLDocument(response);

// get the message you just sent as XML:
var xmlMessage = s.envelope;
[/cc]

Don’t hesitate to contact me if you have any questions.
You can reach me using email on .img[at].img.

Leave a Reply