consuming soap
TRANSCRIPT
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 @ [email protected]
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