Consuming SOAP Web Services

Welcome to FruDevCon 2014!

• Background

• Previous Integrations Team Lead w/ FP

• Software developer background

• UMass Comp Sci Major

• Lives in Boston, MA

• Enjoys playing bass guitar, electronics, hack-a-thons,

motorcycles, traveling and currently learning

Portuguese

2

Paul SenatillakaSenior Developer @ FPpaul.senatillaka@fruitionpartners.com

Agenda

• What is SOAP

• Why SOAP

• SOAP Structure

• What’s a WSDL

• Connectivity

• Security

• Useful Tools

• Consuming SOAP

• Processing SOAP

3

What is SOAP?

• Simple Object Access Protocol

• Originally built as a stop gap

• Applications typically communicated with things

like Remote Procedure Calls (RPC) but there was

no framework for doing the same things over

HTTP

• SOAP introduces a formalized structure and

security for HTTP based communications

4

Why SOAP?

• Allows direct communication between systems

over HTTP

• SOAP is very agnostic

• Operating system

• Programming Language

• Browser

• Highly extensible

• Simpler than many alternatives like RPC

5

SOAP Structure

• At the core, SOAP is an XML document

• Sent to a specific endpoint (URL)

• With some core elements specific to SOAP

• These specific elements are what tell each system:

• That it is a soap message

• How to validate the source (security)

• What to do

• What happened

6

SOAP Structure

7

EnvelopeSOAP message containerEndpoint – Who

HeaderAuthentication

BodyData Content

SOAP Structure - Envelope

• Envelope – Core element that defines the

document as a SOAP message

8

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:imp=http://www.service-now.com/imp_notification>………</soapenv:Envelope>

soapenv namespace defines this as a soap document

Namespace url defines the base structure for soap

Endpoint namespace & url defines the extended soap structure specific to your endpiont

SOAP Structure - Header

• Header – A header element for things like certificates and

authentication

• Can be blank, must always be first child under Envelope

9

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:imp=http://www.service-now.com/imp_notification>

<soapenv:Header><ds:SignatureValue xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

fwjxJRiDNrNxbVsKoHZflsmKlYADldJf0BoN3R2Fx9rjpszFXI2Gp92eXsP+Sl6rmbPXIdKb8lLl+dv8upl8WYPrKJP61KeJ0ZsKNDX474NYC2XEzdJcXbZNktmqY0dSmKwJZzi8rJtmGrbOUAaH51GKoXV2FLJ0AqILoZMyP/SPWKbOUNUCpssY7vRA+tX8ZmrjTwMUvpOZbo+KInPmwfpZ6n/uarOh5zjLNaYJylTCjuuqXDKPZLvDqy48yrsGAWczB901KwLLrE8C+6aPucFrTBytX91vIhaWiLZuba8NouazvUkjUk7LM5o87MGrSFx3OwxbaOD7/cMtdg2bxA==

</ds:SignatureValue></soapenv:header>

……</soapenv:Envelope> Inside the header, you can include things like digital

signatures, certificates, authentication, etc.

SOAP Structure - Body

• Body – The detail of the data being sent/received

10

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:imp="http://www.service-now.com/imp_notification">

<soapenv:Header/><soapenv:Body>

<imp:insert><!--Optional:--><assignment_group>Software Support</assignment_group><!--Optional:--><category>Software</category><comments>Comments are required</comments>

</imp:insert></soapenv:Body>

</soapenv:Envelope>

First child under body typically indicates the action being taken

SOAP Structure - Fault

• Fault – Dedicated element for errors and status details

• Is used in a SOAP response message

• Is a child of the Body element

• It is not required, some applications include error info in their own tags in

the body

11

<soapenv:Envelope…..><soapenv:Header/><soapenv:Body>

<imp:fault><faultcode>numerical code</faultcode><faultstring>string explanation</faultstring><faultactor>string of who/what caused the fault</faultactor><detail>string of more verbose details</details>

</imp:fault></soapenv:Body>

</soapenv:Envelope>

What’s a WSDL

• Web Service Description Language

• Describes a web service

• Is an XML document

• A WSDL is basically your API document for a Web

Service

• It provides all the actions and responses and

elements available for each of them

12

What’s a WSDL

13

Connectivity

• SOAP messages are delivered over HTTP post

• The message is sent to what is called the

“endpoint”

• The endpoint is basically a destination (URL) to a

service listening for incoming HTTP posts

• The receiving service will receive the post,

process the message, and then send a response

back over the bound http session

14

Connectivity

• SOAP interaction can be handled in two ways

• Synchronously

• Synchronous interaction means that an HTTP session is bound, the message is delivered, and a full response is sent, and then the session is closed

• No follow-up response is necessary as all relevant information is included in the original response

• You CANNOT use a MID Server to send a synchronous message

• Asynchronously

• Asynchronous interaction means that the initial response is minimal and that a follow-up message will be sent at some point in the future

• When sending from ServiceNow, you can send asynchronously either by sending it to the ECC Queue or by routing it through a MID Server

15

Security

• There are many types of security supported as

part of a SOAP integration

• Some examples are:

• Basic authentication

• WS Security

• Mutual authentication

• Refer to API documentation for availability

16

Useful Tools

• SoapUI – A great tool that allows you to import a WSDL and automatically

generate sample soap messages to test with

• http://www.soapui.org/

• SOAP Message module – A module in ServiceNow that is very similar to

SoapUI in that you can import a WSDL and auto-generate stub soap

messages

• http://wiki.servicenow.com/index.php?title=Web_Service_Consumer_Support

• FreeFormatter – A website that will reformat difficult to read code by

adding indention. Supports xml, json, etc.

• http://www.freeformatter.com/

17

Consuming SOAP

18

This

Not this

Consuming SOAP – SOAP Message

19

After wsdl is evaluated, all available message functions are pre-loaded

After wsdl is processed, all available message functions are pre-loadedWSDL can be pulled from a URL or

copied/pasted manually

UI Action will evaluate the WSDL and create stub code

Consuming SOAP – Message Functions

20

Each message can have separate authentication and endpoint infoEach message can have separate authentication and endpoint info

Pre-loaded Envelope has all the XML for this function

Parameters allow you to use variables to easily replace/insert values into your soap message

Parameters allow you to use variables to easily replace/insert values into your soap message

The “value” is the default value used when you use the “test” UI Action

Consuming SOAP - Testing

• Clicking the “Test” UI Action on the SOAP Message Function will

automatically send a request using your parameter’s default values and

capture the response.

21

SOAP Message

SOAP Response

Consuming SOAP – With Code

• Clicking the “Preview Script Usage” UI Action on

the SOAP Message Function will give you example

code

22

SOAP Message

SOAP Message Function

Send Message

Set value of short_descparameter

Processing SOAP

23

This

Not this

We’ll explain how to parse XML two different ways in the next slides.

Processing SOAP - XPATH

• XPath is an expression structure that makes it easy to work with and traverse XML

• A single slash / is used as a level separator

• A double slash // is used as a relative path separator

• An @ symbol represents an attribute

• Brackets [] indicate occurrence

24

<?xml version="1.0" encoding="ISO-8859-1"?><project_resources>

<person type="Employee"><first_name>Chad</first_name><last_name>Whaley</last_name><company>Fruition Partners</company>

</person></project_resources>

var msg = new SOAPMessage(‘example’, ‘get’);var xmlexample = msg.post();var xmldoc = new XMLDocument(xmlexample);var first = xmldoc.getNodeText(“/project_resources/person/first_name”);var last = xmldoc.getNodeText(“//person/last_name”);

Response content actually put into the xmlexample variable

Processing SOAP - XMLHelper

• The XML Helper is a special helper class in ServiceNow that will convert XML into a

JavaScript Object

25

<?xml version="1.0" encoding="ISO-8859-1"?><project_resources>

<person type="Employee"><first_name>Chad</first_name><last_name>Whaley</last_name><company>Fruition Partners</company>

</person><person type=”Contractor">

<first_name>Joe</first_name><last_name>Knows</last_name><company>JoeKnows</company>

</person></project_resources>

var msg = new SOAPMessage(‘example’, ‘get’);var xmlexample = msg.post();var helper = new XMLHelper(xmlexample);var converted = helper.toObject();var first = converted[‘person’][0].first_namevar second = converted[‘person’][1].first_nameJSUtil.logObject(converted);

Log ObjectObject

person: Array of 2 elements[0]: Object

@type: string = Employeefirst_name: string = Chadlast_name: string = Whaleycompany: string = Fruition Partners

[1]: Object@type: string = Contractorfirst_name: string = Joelast_name: string = Knowscompany: string = JoeKnows

Consuming SOAP Web Services

Q&A

26