7-1-1 xml services developers guide

XML ServicesDevelopers Guide

Version 7.1.1

January 2008

webMethods

TitlePage

ThisdocumentappliestowebMethodsIntegrationServerVersion 7.1.1andwebMethodsDeveloperVersion 7.1.1andtoallsubsequentreleases.

Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions.

CopyrightSoftwareAG2008.

Allrightsreserved.

ThenameSoftwareAGand/orallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.Othercompanyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners.

Document ID: DEV-XML-DG-711-20080128

Copyright& DocumentID

Table of Contents

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1. Submitting and Receiving XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Example: Submitting XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Example: Receiving XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Example: Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . 11

Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Example: Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15FTPing a File from a webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 16Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Example: Sending XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2. Using the Load and Query Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19What Are the Load and Query Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

What Is Parsing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20What Is a Node? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20What Is a Query? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using the loadXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Adding loadXMLNode to a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Input and Output Values for loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Inputs for loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

The url variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22The method variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23The auth variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24The data variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25The headers variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30The encoding variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31The expandDTD variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32XML Services Developers Guide Version 7.1.1 3

The isXML variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Table of Contents

The loadAs variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34The failOnHTTPError variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Output Values from loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Error Handling With loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Using the queryXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Passing a Node to queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Addressing Information in a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Working with a Sample Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

The XML Node View Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38The Sample View Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Adding queryXMLNode to a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Specifying a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Specifying a Query Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Specifying a Query by Pointing to a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using WQL and XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Using WQL in a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

webMethods Predefined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Specifying Multiple Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Nested Element References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48The Scope of a WQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Referencing Data in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Using Search Strings as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Wildcard Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Regular Expressions as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Attribute Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Matching on the Name Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Using Masks to Extract Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Regular Expressions in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Using Lines to Select Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Using Character Ranges to Extract Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Using XQL in a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Specifying a Method in XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Specifying Multiple Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Nested Element References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Using Search Strings as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Specifying Elements with Particular Namespaces . . . . . . . . . . . . . . . . . . . . . 59Specifying Elements with Boolean Expressions . . . . . . . . . . . . . . . . . . . . . . . 59Specifying Elements with Comparison Operators . . . . . . . . . . . . . . . . . . . . . 59

Quick Reference: WQL vs. XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Output from queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Handling Errors from queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 XML Services Developers Guide Version 7.1.1

Table of Contents

Load and Query Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Generating Default Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Creating a Load and Query Service from a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

A. webMethods Query Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Object References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Sibling Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Property Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71XML Services Developers Guide Version 7.1.1 5

Table of Contents

6 XML Services Developers Guide Version 7.1.1

About This Guide

ThisguideisforuserswhowanttosubmitandreceiveXMLdocumentswithwebMethodsDeveloper,convertXMLdocumentstoISdocuments(andviceversa),andqueryXMLdocumentsusingXQLorWQL.

Document Conventions

Additional InformationThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyouwithimportantsourcesofinformationaboutwebMethodsproducts:

Troubleshooting Information.ThewebMethodsKnowledgeBaseprovidestroubleshootinginformationformanywebMethodsproducts.

Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,gototheDocumentationFeedbackFormonthewebMethodsBookshelf.

Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthedocumentationduringproductinstallationtoasingledirectorycalled_documentation,locatedbydefaultunderthewebMethodsinstallationdirectory.Inaddition,youcanfinddocumentationforallwebMethodsproductsonthewebMethodsBookshelf.

Convention Description

Bold Identifieselementsonascreen.Italic Identifiesvariableinformationthatyoumustsupplyorchangebased

onyourspecificsituationorenvironment.Identifiestermsthefirsttimetheyaredefinedintext.Alsoidentifiesserviceinputandoutputvariables.

Narrow font IdentifiesstoragelocationsforservicesonthewebMethodsIntegrationServerusingtheconventionfolder.subfolder:service.

Typewriter font

Identifiescharactersandvaluesthatyoumusttypeexactlyormessagesthatthesystemdisplaysontheconsole.

UPPERCASE Identifieskeyboardkeys.Keysthatyoumustpresssimultaneouslyarejoinedwiththe+symbol.

\ Directorypathsusethe\directorydelimiterunlessthesubjectisUNIXspecific.

[] Optionalkeywordsorvaluesareenclosedin[].Donottypethe[]symbolsinyourowncode.XML Services Developers Guide Version 7.1.1 7

About This Guide

8 XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17XML Services Developers Guide Version 7.1.1 9


OverviewYoucansubmitXMLdocumentstothewebMethodsIntegrationServerfromaclient,andhavetheIntegrationServerreceiveXMLdocumentswithservicesthatyouwrite.TheIntegrationServerprovidesthefollowingautomatedmechanismsforreceivingarbitraryXMLdocuments,parsingthem,andpassingthemasinputtoaspecifiedservice.

AclientsubmitsanXMLdocumenttoaserviceinaStringvariable(ofanyname),whichthetargetserviceconvertsintoanodeusingpub.xml:xmlStringToXMLNode.

AclientsubmitsanXMLdocumenttoaserviceinaspecialStringvariablenamed$xmldata,andwebMethodsIntegrationServerautomaticallyparsesthevariableandpassesittotheserviceasanode.

AclientpostsanXMLdocumenttoaserviceviaHTTP. AclientFTPsanXMLdocumenttoaservice. AclientemailsanXMLdocumenttoaservice. AclientsendstheXMLdocumentasanemailattachment.

Submitting and Receiving XML in a String VariableOnewaytosubmitanXMLdocumenttothewebMethodsIntegrationServeristopasstheentireXMLdocumenttoaserviceinaStringvariable.Whenyouusethisapproach,youshouldcodethetargetservicetoexecutepub.xml:xmlStringToXMLNodetoconverttheStringvariable(thatis,theXMLdocument)toanode.OncetheXMLdocumentisrepresentedasanode,itexistsinaformthatcanbequeriedorconvertedtoanIDataobject.ForinformationaboutusingxmlStringToXMLNode,seethewebMethodsIntegrationServerBuiltInServicesReference.

Example: Submitting XML in a StringThefollowingcodefragmentshowshowaJavaclientmightsubmitanXMLdocumenttoaservicecalledpurch:postOrderonwebMethodsIntegrationServer.Inthisexample,theclient:

1 LoadstheXMLdocumentintoaString

2 PutstheStringintotheelementordersinanIDataobjectnamedinputs

3 Invokespurch:postOrderontheserveratlocalhost:555510 XML Services Developers Guide Version 7.1.1


Example: Receiving XML in a StringOntheserver,thereceivingserviceshouldbecodedtopasstheXMLintheStringvariabletopub.xml:xmlStringToXMLNode.ThisproducesanodethatcanbesubsequentlyqueriedorconvertedtoanIDataobject.

Inthepreviousexample,purch:postOrdershouldbecodedtopasstheXMLdocumentinorderstopub.xml:xmlStringToXMLNode.Forinformationabouttheservicesthatyoucanusetomanipulatenodes,seepub.xml:queryXMLNodeandpub.xml:xmlNodeToDocumentinthewebMethodsIntegrationServerBuiltInServicesReference.

Submitting and Receiving XML in $xmldataSubmittinganXMLdocumenttowebMethodsIntegrationServerusing$xmldataissimilartosubmittingitasaStringvariable,butinthiscase,theservicereceivingtheXMLdocumentdoesnotneedtoincludeaparsingstep;webMethodsIntegrationServerautomaticallyparsesthecontentsof$xmldata.

Thename$xmldatahasspecialmeaningtotheIntegrationServerinthatitassumesthevalueofthisvariableisanXMLdocument.Whenitreceivesarequestthatincludesaninputvariablenamed$xmldata,theserverautomaticallyparsesthecontentsofthatvariable,producinganXMLnodethatcanbeusedbyanyservicethattakesanodeasinput.

Example: Submitting and Receiving XML in $xmldataThefollowingexampleshowsaclientapplicationthatreadsanXMLdocumentfromafile,assignsthetextinthefileto$xmldataandthenpasses$xmldatatoaservicecalled

import com.wm.app.b2b.client.*; import com.wm.util.*; import com.wm.data.*; import java.io.*; public class ArbitraryXMLClient . . . //--Load XML into orders string String orders = YourLoadXMLMethod(orderFile); //--Put input values into IData object IData inputs = IDataFactory.create(); IDataCursor inputsCursor = inputs.getCursor(); inputsCursor.insertAfter("orders", orders); inputsCursor.insertAfter("authCode", authCode); //--Submit request to server c.connect("localhost:5555", "null", null); IData outputs = c.invoke("purch", "postOrder", inputs); c.disconnect(); . .

.

2

3

1XML Services Developers Guide Version 7.1.1 11

sales:getOrder.


Theserviceinvokedbythisclientmustbeaservicethattakesanodeasaninputvariable(forexample,queryXMLNode,xmlNodeToDocument),becausethisiswhatwebMethodsIntegrationServerproduceswhenitreceivesthisrequest.

Important! ThisexampleshowsaJavabasedclient;however,anytypeofISclient(evenabrowserbasedclient)canbeused.Withabrowserbasedclient,youwouldposttheXMLdocumentasthevalueportionofa$xmldata=valuepair.YouwouldmostlikelyconstructtheXMLdocumentwithJavascript.Youmaypostothername=valuepairswiththerequest.

import com.wm.app.b2b.client.*; import com.wm.util.*; import com.wm.data.*; import java.io.*; public class ArbitraryXMLClient { public static void main(String args[]) throws Exception { //--Read XML document from a specified file (or from stdin) Context c = new Context(); IData inputs = IDataFactory.create(); IDataCursor inputsCursor = inputs.getCursor(); Reader in = null; if(args.length > 0) { in = new InputStreamReader(new

FileInputStream(args[0])); } else { in = new InputStreamReader(System.in); } char[] buf = new char[8192]; int count = 0; StringBuffer sb = new StringBuffer(); while((count = in.read(buf)) != -1) { sb.append(buf, 0, count); } //--Assign XML document to string variable String xmldata = sb.toString(); //--Put XML document into $xmldata in IData object inputsCursor.insertAfter("$xmldata", xmldata); //--Submit request to server c.connect("localhost:5555", "null", null); IData outputs = c.invoke("sales", "getOrder", inputs); c.disconnect(); //--Display the returned output values System.out.println(outputs); } 12 XML Services Developers Guide Version 7.1.1


Submitting and Receiving XML via HTTPAclientcanpostanXMLdocumenttoaservicethatreceivesitviaHTTP.Tousethisapproach,youmusthaveaclientthatcan:

Sendastringofdata(anXMLdocument)towebMethodsIntegrationServerusingtheHTTPPOSTmethod.

AND

SetthevalueoftheContent-Typerequestheaderfieldtotext/xml.WhenwebMethodsIntegrationServerreceivesanHTTPPOSTrequestwhereContent-Typeistext/xml,itautomaticallyparsesthebodyoftherequest(theXMLdocument)andpassesitasanodetotheservicespecifiedintherequestsURL.

Client RequirementsSincemostbrowsersdonotallowyoutomodifytheContentTypeheaderfield,theyarenotsuitableclientsforthistypeofsubmission.ClientsthatyoumightusetosubmitanXMLdocumentinthismannerarePERLscripts(whichallowsyoutobuildandissueHTTPrequests)orthewebMethodsIntegrationServerservice,pub.client:http.

Regardlessofwhichclientyouuse,itmustdothefollowing:

SubmitaPOSTrequesttowebMethodsIntegrationServer. AddresstherequesttotheURLofanservice(forexample,

http://rubicon:5555/invoke/purch/postOrder).

SettheContentTypeheaderfieldtotext/xml. ContainanXMLdocumentinthebodyofthemessage.Thedocumentmustbethe

onlytextthatappearsinthebodyoftherequest.Donotassignittoaname=valuepair.

Important! WhenyousubmittheXMLdocument,placeanextracarriagereturn/newline(\r\n)attheendofittoindicatetheendoftheXMLdocument.XML Services Developers Guide Version 7.1.1 13


Example: Submitting and Receiving XML via HTTPThefollowingexampledescribesthevaluesthatyousetifyouusepub.client:httptoPOSTanXMLdocumenttoaservice.

YouwillalsosetanyoptionalHTTPparameters,suchasauthorizationinformation,thatarerequiredbyyourapplication.

Submitting and Receiving XML via FTPYoucanFTPanXMLdocumenttowebMethodsIntegrationServersFTPlisteningport.(BydefaulttheFTPportisassignedtoport8021.However,thisassignmentisconfigurable,soyoushouldcheckwithyourwebMethodsIntegrationServeradministratortoseewhichportisusedforFTPcommunicationsonyourwebMethodsIntegrationServer.)

WhenaclientputsafileontheIntegrationServerforthepurposeofinvokingaservice,theFTPListenerwillchooseacontenthandler,basedonthefileextension,toconvertthefilecontentintotheinputvaluesfortheservicetoinvoke.TheIntegrationServerslib/mime.typesfilecontainsthemappingoffileextensiontocontenttype.

WhentheIntegrationServerreceivesanXMLdocumentontheFTPlisteningport,itautomaticallyparsesthedocumentandpassesitasanodetotheserviceinthedirectorywherethefilewasFTPed.

Set this variable... To...

url TheURLoftheservicethatyouwanttoinvoke.Thefollowingvaluewouldinvokethe purch:postOrderservicefromaservernamedrubiconwithportnumber5555.

Example http://rubicon:5555/invoke/purch/postOrdermethod post

headers.ContentType text/xml

data.string

OR

data.bytes

TheXMLdocumentthatyouwanttopost.

Tip! Youcaneditthemappingsinthelib/mime.typesfile(andreloaditwithoutrestartingIntegrationServer),byselectingSettings > Resources > Mime TypesfromtheIntegrationServerAdministratorscreen.14 XML Services Developers Guide Version 7.1.1


TosubmitanXMLdocumenttowebMethodsIntegrationServerviaFTP:

TheXMLdocumentcanbecontainedinafilethathaseither: Afileextensionofxml Afileextensionwhosemimetypeisregisteredwiththeserverastext/xml.

Todothis,edittheIntegrationServerslib/mime.typesfile.Forexample:text/xml mimetype

NofileextensionToconfigureacontenthandlertohandlefilesthathavenoextension,usethespecialkeyftp_no_extensioninthelib/mime.typesfiletoindicateanullextension.Then,specifythecontenttypemappedtoanullextension.Forexample,thefollowingXMLcontenthandlerisusedtohandlefileswithoutanextension:text/xml ftp_no_extension

Ifyouwanttouseadifferentkeytospecifyanullextension,usethepropertywatt.net.ftp.noExtensionKeytospecifythekeyusedinlib/mime.typestospecifyafilewithnoextension.Thedefaultvalueofthispropertyisftp_no_extension.

Theservicetowhichyouwanttopassthedocumentmusttakeanodeasinput.

Client RequirementsIfyouwanttosubmitanXMLdocumenttoaservicethroughFTP,theapplicationsendingthedocumentmustdothefollowing:

1 InitiateanFTPsessiononwebMethodsIntegrationServersFTPlisteningport.

2 PointtothedirectorythatcontainstheservicetowhichyouwanttopasstheXMLdocument.

Example cd \ns\Purchasing\SubmitOrder

3 CopytheXMLdocumenttothisdirectoryusingthefollowingcommand:put XMLDoc.xml

orput XMLDoc

WhereXMLDocisthenameofthefilethatyouwanttopasstowebMethods

Important! NotethattherootdirectoryforthisoperationisyourwebMethodsIntegrationServersnamespacedirectory(ns),nottherootdirectoryofthetargetmachine.Therefore,ifyouwanttoFTPafiletoaserviceinthePurchasingpackage,youuse\ns\Purchasing\ServiceNameasthepathtothatservice,notIntegrationServer_directory\ns\Purchasing\ServiceName.XML Services Developers Guide Version 7.1.1 15

IntegrationServer.Thefileextensioncanbesomethingotherthanxmlifthe


extensionsmimetypeisregisteredwiththeserverastext/xml.Alternatively,thefileextensioncanbeomittedifyouspecifythespecialkeyftp_no_extensioninthelib/mime.typesfiletoindicateanullextension.SeeSubmittingandReceivingXMLviaFTPonpage 14fordetails.

Example put PurchaseOrder.xml

NotethattheXMLdocumentyouFTPtowebMethodsIntegrationServerisneveractuallywrittentotheserversfilesystem.TheXMLdocumentyousendandtheoutputfileitproduces(seebelow),arewrittentoavirtualdirectorysystemmaintainedinyourISsession.

FTPing a File from a webMethods Integration ServerThepub.clientfoldercontainsbuiltinservicesyoucanusetoFTPafilefromawebMethodsIntegrationServer.Forinformationabouttheseservices,seethewebMethodsIntegrationServerBuiltInServicesReference.

Receiving XML via FTPTheresultsfromaserviceexecutedbyanFTPrequestarewrittentothesamevirtualdirectorywheretheXMLdocumentwasinitiallyFTPed.

Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresults(thatis,thecontentsofthepipeline)areXMLencodedandreturnedasanXMLdocument.

IftheservicehasanXMLoutputtemplateassignedtoit,thattemplateisappliedtotheresults.(IfthetemplateisnotanXMLbasedtemplate,itisnotapplied.)

Thenameoftheoutputfiletowhichresultsarewrittenis:XMLDoc.xml.out

WhereXMLDoc.xmlisthenameoftheXMLfileinitiallyFTPedtotheservice.(Thefileextensioncanbesomethingotherthanxmliftheextensionsmimetypeisregisteredwiththeserverastext/xml.)

YouretrievethisXMLdocumentusingtheFTPgetcommand.Forexample,ifyouputanXMLdocumentcalledPurchaseOrder.xmlonwebMethodsIntegrationServer,youwouldusethefollowingFTPcommandtogetitsresults:

Example get PurchaseOrder.xml.out

WhenyouendtheFTPsession,webMethodsIntegrationServerautomaticallydeletestheoriginalfileanditsresultsfromyoursession.

Important! WerecommendthatyouuseauniquenameforeachXMLdocumentthatyouFTPtowebMethodsIntegrationServer(perhapsbyattachingatimestamptothename)sothatyoudonotinadvertentlyoverwriteotherFTPedXMLdocumentsortheirresultsduringanFTPsession.16 XML Services Developers Guide Version 7.1.1


Submitting and Receiving XML via E-mailYoucanemailanXMLdocumenttoanemailmailboxandhavewebMethodsIntegrationServerautomaticallyretrievetheemailmessageandprocesstheXMLdocumentitcontains.Todothis,yourwebMethodsIntegrationServermustbeconfiguredwithanemailportthatmonitorsthemailboxtowhichtheXMLdocumentwillbesent.(ConsultyourwebMethodsIntegrationServeradministratortoseewhetheranemailporthasbeensetuponyourwebMethodsIntegrationServer.)

WhenanXMLdocumentarrivesintheemailportsmailbox,webMethodsIntegrationServerautomaticallyretrievesthemessage,parsestheattachedXMLdocument,andpassestheXMLdocumentasanodetotheservicespecifiedontheemailssubjectline(or,ifaserviceisnotspecifiedonthesubjectline,theemailportsdefaultservice).

Client RequirementsTosubmitanXMLdocumenttowebMethodsIntegrationServerviaemail,yourclientprogrammust:

PuttheXMLdocumentinanemailattachment. SettheemailsContent-Typeheadertotext/xml. SpecifythenameoftheservicethatwillprocesstheXMLdocumentintheemails

subjectline.Ifyouleavethesubjectlineempty,theXMLdocumentwillbeprocessedbytheglobalserviceifoneisdefinedor,ifnot,bythedefaultserviceassignedtotheemailport(ifonehasbeenassigned).Forinformationaboutspecifyingtheportsdefaultservice,seethewebMethodsIntegrationServerAdministratorsGuide.

TheservicethatprocessestheXMLdocumentmusttakeanodeasinput.

Example: Sending XML via E-mailThefollowingexampledescribesthevaluesthatyouwouldsetifyouusedpub.client:smtptoemailanXMLdocumenttoaservice.(Formoreinformationaboutusingthisservice,seethewebMethodsIntegrationServerBuiltInServicesReference.)

Set this variable... To...

to AStringspecifyingtheemailaddressthatwebMethodsIntegrationServersemailportmonitors.

subject AStringspecifyingthefullyqualifiednameoftheservicethatwebMethodsIntegrationServerpassestheattachedXMLdocumentto.

Example: orders:ProcessPO

Ifyoudonotspecifysubject,theemailportwillinvokeitsdefaultservice(ifonehasbeenassignedtoit).XML Services Developers Guide Version 7.1.1 17


Receiving XML via E-mailIfyouremailportisconfiguredtoreturnresults,theresultsfromaserviceinvokedthroughtheportareemailedbacktothesenderoftheoriginalmessage,inanattachmentfilecalledxml.out.

Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresultsfromtheservice(thatis,thecontentsofthepipeline)areXMLencodedandreturnedasanXMLdocument.

Iftheservicehasanoutputtemplateassignedtoit,thattemplateisappliedtotheresults.

from AStringcontainingtheemailaddresstowhichtheresultsoftheservicearesent.

body AStringcontaininginputparametersfortheserviceinURLquerystringformat.Thefollowingexamplesetsfiveparameters:one,two,andthreearesettothevalues1,2and3,respectively.Theparameters$userand$passhavespecialmeaningtotheemailport.Youusetheseparameterstospecifytheusernameandpasswordfortheemailport.Youmustspecifythesetwoparametersifauthenticationisenabledontheemailport.

Example:one=1&two=2&three=3&$user=Administrator&$pass=manage

attachments.contenttype AStringsetto:text/xml

attachments.content

OR

Thebyte[]oraStringcontainingtheXMLdocument.

attachments.filename AStringspecifyingthefullyqualifiednameofthefilecontainingtheXMLdocument.

Important! Bydefault,theemailportdoesnotreturnanyresultsfromrequeststhatitreceives.Ifyouwanttheporttoreturnresults,youmustexplicitlyconfigureittodoso.Forinformationaboutconfiguringtheemailporttoreturnresults,seethewebMethodsIntegrationServerAdministratorsGuide.

Set this variable... To...18 XML Services Developers Guide Version 7.1.1

2 Using the Load and Query Services

What Are the Load and Query Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using the loadXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Using the queryXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Load and Query Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61XML Services Developers Guide Version 7.1.1 19


What Are the Load and Query Services?ThewebMethodsIntegrationServerisequippedwithasetofloadandqueryservicesthatallowyoutofetchHTMLorXMLdocumentsviaHTTPorHTTPSandselectivelyextractinformationfromthemforotherservices.Throughtheseservices,youcanconnectaservicetovirtuallyanydocumentontheInternet.(Ifyouwanttoretrievedocumentsfromalocalfilesystem,seepub.file:getFileinthewebMethodsIntegrationServerBuiltInServicesReference.)

FetchinganXMLdocumentfromtheInternetwithwebMethodsIntegrationServerisatwostepprocess.

First,youusethepub.xml:loadXMLNodeservicetoretrievethedocumentthatcontainstheinformationyouneed.

Next,youextractthepiecesofinformationyouneedtouseandassignthemtoISvariables.Forthisstep,youcanusethepub.xml:queryXMLNodeservice(toselectspecificelementsfromthedocument)orthepub.xml:xmlNodeToDocumentservice(toconvertallelementsinthedocumenttovariables).

Basic ConceptsTosuccessfullyusewebMethodsIntegrationServersloadandqueryservices,youshouldunderstandthefollowingtermsandconcepts.

What Is Parsing?ParsingistheoperationthattheserverperformstoconvertanXMLdocument(astring)intoanXMLnodewhoseelementscanbeaddressedandextractedbyservices.webMethodsIntegrationServerautomaticallyparsesXMLdocumentsthatyoufetchwiththeloadXMLNodeservice.

What Is a Node?Anodeistheresultofaparsingoperation.ItisanelementbasedrepresentationofanXMLdocument.Thenodeexpressesadocumentinatreelikestructurethatallowsthedatawithinittobeefficientlyaddressedandlinkedintoservices.

What Is a Query?WithrespecttoXMLnodes,aqueryisanexpression,writtenintheXMLQueryLanguage(XQL)orthewebMethodsQueryLanguage(WQL)thatyouusetoextract(filter)informationfromXMLnodes.20 XML Services Developers Guide Version 7.1.1


Using the loadXMLNode ServiceYouusethepub.xml:loadXMLNodeservicetoretrieveanXMLorHTMLdocumentfromtheInternet.Thisservicedoesthefollowing:

ItsubmitsaHTTPorHTTPSrequestforaspecifiedXMLorHTMLdocument.ANDTHEN

Itparsesthereturneddocument.TheoutputfromloadXMLNodeisanXMLnodethatcanbeusedwithanyservicethattakesadocumentoranodeasinput.

Adding loadXMLNode to a Flow ServiceThefollowingproceduredescribesthestepsyouusetoinsertpub.xml:loadXMLNodeintoaflowservice.

1 OpentheserviceinwhichyouwanttoinsertloadXMLNode.

2 Click ontheeditortoolbar,andselectloadXMLNode.(IfloadXMLNodedoesnotappearonthemenu,clickBrowseandselectpub.xml:loadXMLNodefromthelistnexttoFolder.)

3 ClickthePipelinetabifitisnotalreadydisplayed.

4 CompletethefollowingstepstospecifytheURLofthedocumentthatyouwanttoretrieve.

a InServiceIn,selecturl.

b Click onthetoolbar.

c TypetheURL,startingwithhttp:orhttps:,andthenclickOK.

ExamplesThefollowingstringwouldretrievethespecifieddocumentviahttp:http://www.rubicon.com/orders/orders.xml

Note: Ifyouwanttofetchadocumentfromalocalfilesystem,donotuseloadXMLNode.Instead,usethepub.file:getFileservice.

Important! ThefollowingprocedureexplainshowtomanuallyinsertandspecifytheloadXMLNodeservice.Ifyouareconstructingaloadandqueryservice,however,youmaywanttousethewizardinstead.ThiswizardallowsyoutobuildaloadandquerysequencebypointingtoaURL.Forinformationaboutusingthewizardtocreatealoadandquerysequence,seeLoadandQueryShortcutsonpage 61.

To insert loadXMLNode into a flow serviceXML Services Developers Guide Version 7.1.1 21


Thefollowingstringwouldretrievethedocumentviahttps:https://www.rubicon.com/orders/orders.xml

5 Usethe SetValuemodifiertoassignvaluestotheremaininginputvariablesasneeded.FormoreinformationabouttheinputvariablesforloadXMLNode,seeInputsforloadXMLNodeonpage 22.

Input and Output Values for loadXMLNodeTheinputsforloadXMLNodespecifywhatdocumentyouwanttoretrieve,whatdata(ifany)youwanttosubmitwiththerequest,andhowyouwantwebMethodsIntegrationServertoparsethedocumentitreceives.

WhenyouuseloadXMLNodeinaflowservice,youusethe Set ValuemodifierinthePipelinetabtoassignvaluestothesevariables.IfyoucallloadXMLNodefromaprogram,yourprogrammustsetthesevariablesintheIDataobjectitpassestothepub.xml:loadXMLNodeservice.

Service inputs for loadXMLNode

Inputs for loadXMLNodeThefollowingdescribestheinputvaluesusedbytheloadXMLNodeservice.

The url variableSetthisvariabletospecifytheURLofthedocumentyouwanttoretrieve.

Example http://www.rubicon.com/orders/orders.html

Thevalueyouspecifymustbeastringthatstartswiththeprotocolspecifierhttp:orhttps:

Use the Set Valuemodifier to assign

input values toloadXMLNode.22 XML Services Developers Guide Version 7.1.1


Youmayincludeaquerystring(forexample,acollectionofname=valuepairs)withthestringthatyouspecify.However,wesuggestthatyouusethedatavariableforthistypeofinformationinstead.Itisusuallyamorepracticalplaceforname=valuedata,becauseitallowsyoutolinkindividualvariablesinthequerystring.SeeThedatavariableonpage 25.

Dooneofthefollowing:

Usethe Linkmodifiertoassignapipelinevariabletourl.OR

Usethe Set ValuemodifierinthePipelinetabtospecifytheURLyouwanttouse.

The method variableSetthisvaluetospecifytheHTTPmethod(GETorPOST)thatyouwantthetargetservertoexecuteontheresourcespecifiedinurl.ThisvaluedeterminesthewayinwhichloadXMLNodesubmitsdatavalues(ifany)totheresourceidentifiedinurl.

Ifyousetmethodtoget,loadXMLNodeappendsthevaluesyouspecifyindatatothevalueinurl.(NotethatonlycertaindataelementsarevalidwhenyouusetheGETmethod).

Ifyousetmethodtopost,loadXMLNodesendsthevaluesindatainthebodyoftheHTTPorHTTPSrequest.


Usethe Linkmodifiertoassignapipelinevariabletomethod.OR

Usethe Set ValuemodifierinthePipelinetabtoselectthemethodyouwanttouse.

Setting the method variable in a flow service

To assign url in a flow service

To assign method in a flow service

Select get or postfrom the list.XML Services Developers Guide Version 7.1.1 23


The auth variableYouusethisvariabletospecifytheauthorizationandauthenticationcredentials(forexample,usernameandpassword)thatyouwantloadXMLNodetosubmitwhenitrequeststhespecifieddocument.

Tosettheauthvariablecorrectly,youmustknow:

WhethertheInternetresourceyouareaccessingisprotectedand,ifso,whattypeofauthenticationisrequiredtoaccessit.Iftheresourceisnotprotected(thatis,itdoesnotrequireausernameandpassword)youdonotneedtosetanyoftheelementsinauth.

Theusernameandpasswordthatisrequiredbytheresourceyouarerequesting.Iftheresourceyouarerequestingisprotected,youmustspecifytheauthvariablewhenyouuseloadXMLNode.EachelementinauthspecifiesapieceoftheAuthorizationfieldthatloadXMLNodewillsubmittothetargetserver.


Usethe Linkmodifiertoassignapipelinevariabletothetype,user,and/orpasselementsasneeded.

OR

Usethe Set ValuemodifierinthePipelinetabtohardcodethetype,user,and/orpasselementsasneeded.

Set this element... To specify...

type Theprotectionschemeusedtocontrolaccesstotherequesteddocument.Ifyouareaccessingaprotectedresource,settoBasic.

user Ausernamethathasauthoritytoaccesstheresourcespecifiedinurl.

Thisvaluedefaultstothevalueofwatt.net.httpUserintheserversconfigurationfile(server.cnf).

pass Thepasswordassociatedwiththeusernamespecifiedinuser.Iftheuserdoesnotrequireapassword,leavepassempty.

Thisvaluedefaultstothevalueofwatt.net.httpPassintheserversconfigurationfile(server.cf).

To assign auth in a flow service24 XML Services Developers Guide Version 7.1.1


The data variableUsethedatavariabletospecifydatathatyouwantloadXMLNodetosubmittotheresourceidentifiedinurl.

ThedatavariableisaDocumentthatcontainsseveralpredefinedelements.Eachelementallowsyoutospecifydatainadifferentway.(NotethatsomeelementsarevalidforonlyoneHTTPmethod:GETorPOST.)

Important! Ifyouincludeyourdatawiththestringinurl,donotspecifyavalueindata.

Note: Ifyousubmitdatausingtheargsortableelement,loadXMLNodeautomaticallysetstheHTTPContentTypeheadertoapplication/x-www-form-urlencoded.IfyouwanttospecifyadifferentContentType,usethestringorbyteselementtosubmityourdata,notargsortable.

Use this element... If you want to...

args Specifyname=valuepairsasstringelementsinaDocument.Whenyouspecifydatainthismanner,loadXMLNodeautomaticallyappendstheelementsfromargstourl(ifyouareusingtheGETmethod)orinsertstheminthebodyofthemessage(ifyouareusingthePOSTmethod).

Tospecifydatainthismanner,createonestringelementforeachname=valuepairthatyouwanttosubmit,where:

Thenameoftheelementdefinesthenameportionofthepair,and

Thevalueoftheelementspecifiesthevalueportionofthepair.NotethatloadXMLNodewillautomaticallydothefollowing:

URLencodevaluesyouspecify. Insertthe&characterbetweeneachname=valuepairthatit

constructsfromtheargs(forPOSTandGET).Youdonothavetoincludethischaracterinthevaluesyouspecify.

Insertthe?characteratthebeginningofthequerystringitgeneratesfromargsfortheGETmethod.Youdonothavetoincludethischaracterinthevaluesyouspecify.

Important! Ifyouneedtospecifymultiplevaluesforasinglevariable(forexample,a=b&a=c&a=d),usethetableelement.XML Services Developers Guide Version 7.1.1 25


Note: WhenyouusemorethanoneelementtosubmitdatawithloadXMLNode,argsisappendedfirst,tableisappendedsecond,andstringisappendedlast.

ThefollowingproceduredescribeshowtousethePipelinetabtoassigndatatoargsinaflowservice.

To assign name=value pairs in args

1 SelecttheloadXMLNodestepintheeditor,andthenclickthePipelinetab.

2 InService In,selectargs.

3 Click onthetoolbarandselectString.

4 Typethenameportionofthefirstname=valuepair,andpressENTER.

5 Click tomakethatelementachildofargs.

6 Ifyouwanttoassignahardcodedvaluetothiselement,dothefollowing:

a Click onthetoolbartoopentheInput fordialogbox.

b Typethevalueportionofthename=valuepair.YoudonotneedtoURLencodethevalueifyouareusingtheGETmethodtosubmitdatabecauseloadXMLNodewilldothisatruntime(forexample,itwillconvertGlobalSportingGoodstoGlobal+Sporting+Goods).

c ClickOK.

7 Toassignthevalueofapipelinevariableforargs,selectargsandtheappropriatevariableinPipeline Inandthenclick tocreatealinkbetweenthem.

8 Repeatsteps 37foreachname=valuepairyouwanttosubmit.

Use this element... If you want to...26 XML Services Developers Guide Version 7.1.1


Use this element... If you want to...

table Specifyyourdatainatwocolumntableofstrings.Whenyouspecifydatainthismanner,loadXMLNodeautomaticallyappendstheelementsfromtabletourl(ifyouareusingtheGETmethod)orinsertstheminthebodyofthemessage(ifyouareusingthePOSTmethod).

Thetablevariableissimilartotheargsvariable;however,tableallowsyoutosubmitvaluesthatarenotpartofaname=valueconstruction.Forexample,ifyourInternetresourceexpectsasetofunnamedvaluessuchashttp://www.rubicon.com/orders?GSG&40019&openinsteadofname=valuepairs,youmustspecifythosevaluesintable.Thisisbecauseargsonlyproducesname=valuepairs.

Tosubmitdataviathetableelement,createarowforeachvariablethatyouwantloadXMLNodetosubmit,where:

Thecontentsofcolumn0specifythenameportionofthepair(ifitisanunnamedvariable,leavethiscellblank),and

Thecontentsofcolumn1specifythevalueportionofthepair.NotethatloadXMLNodewillautomaticallydothefollowing:

URLencodevaluesyouspecify. Insertthe&characterbetweeneachname=valuepairthatit

constructsfromtable(forbothPOSTandGET).Youdonothavetoincludethischaracterinthevaluesyouspecify.

Insertthe?characteratthebeginningofthequerystringitgeneratesfromtablefortheGETmethod.Youdonothavetoincludethischaracterinthevaluesyouspecify.

Important! WhenyouuseargsandtabletosubmitdatawithloadXMLNode,theserviceappendsargsfirstandtablesecond.Theserviceappendsstringlast.XML Services Developers Guide Version 7.1.1 27


ThefollowingproceduredescribeshowtousethePipelinetabtoassigndatatotableinaflowservice.

To assign name=value pairs in table


2 InService In,selecttable.

3 Ifyouwanttoassignasetofhardcodedvaluestotable,dothefollowing:


b Click twicetocreatetwocolumns(0and1).

c Click tocreateanemptyrow.

d Selectcell0andtypethenameofthename=valuepairthatyouwanttosubmittotheInternetresourceinurl.(Ifyouaresendinganunnamedvariable,leavethiscellempty.)

e Selectcell1andtypethevalueofthename=valuepairthatyouwanttosubmittotheInternetresourceinurl.(Ifspecifyinganunnamedvariable,typethevariablesvalue.)

f Repeatsteps ceforeachvariablethatyouwanttospecify.

g ClickOK.

4 Toassignthevalueofapipelinevariablefortable,selecttableandtheappropriatevariableinPipeline Inandthenclick tocreatealinkbetweenthem.(Notethatthevariableyoulinktotablemustbeatwocolumntableofstrings.)

Use this element... If you want to...28 XML Services Developers Guide Version 7.1.1


string Specifyyourdataasasinglestringoftext.Whenyouspecifydatainthismanner,loadXMLNodeautomaticallyappendsthespecifiedstringtourl(ifyouareusingtheGETmethod)orinsertsitintothebodyofthemessage(ifyouareusingthePOSTmethod).

KeepthefollowingpointsinmindwhenyouusestringtosubmitdatawithloadXMLNode.

Ifyouarespecifyingasetofname=valuepairs,stringmuststartwiththefirstnameintheset.

ExampleAccountNum=GSG-970414A

Youdonotneedtoincludethe?symbolatthebeginningofthestringbecauseloadXMLNodewillautomaticallyinsertthissymbolwhenitappendsstringtothecontentsofurl.

IfyouareusingtheGETmethod,besuretoformatstringasavalidquerystring.Thatis,separatevariableswiththe&character(asshowninExample1)andURLencodetheirdatavalues(asshowninExample2).

Example 1AccountNum=GSG-970414A&postalCode=22031

Example 2 CompanyName=Global+Sporting+Goods

IfyouareusingthePOSTmethod,formatthestringexactlyasyouwantittoappearinthebodyofthemessage.

Important! WhenyouusemorethanoneelementtosubmitdatawithloadXMLNode,argsisappendedfirst,tableisappendedsecond,andstringisappendedlast.

bytes Specifyyourdataasanarrayofbytesthatyouwantpostedtotheresourceinurl.YoucanusethisvariablewhenyouneedtosendnontextualdatatoanInternetresource.

Toassignavaluetobytesinaflowservice,usethePipelinetabtolinkthevariablecontainingyourbytearraytobytes.

Important! loadXMLNodeonlyusesthebyteswhenmethodissettoPOST.

Note: Whenyouusebytesandanotherelement(args,table,orstring)tosubmitdatawithloadXMLNode,theserviceappendsthedatafromtheargs,table,orstringelementtourl.Theserviceappendsargstourlfirst,tablesecond,andstringlast.Theserviceencodesthedatafromthebyteselementinthebodyofthepost.

Use this element... If you want to...XML Services Developers Guide Version 7.1.1 29


The headers variableYouusethisvariableifyouwanttospecifythevalueofaheaderfieldintheHTTPrequestthatloadXMLNodesubmitstothetargetserver.

Bydefault,loadXMLNodeissuesastandardsetofheaderfields.(ThevaluesofsomeofthesefieldsareconfiguredwhenyourwebMethodsIntegrationServerisinstalled.Consultyourserveradministratorifyouwanttoknowyourserversdefaultsettings.)Touseaheadervalueotherthanthedefault,youcanspecifyitintheheadersvariable.

IfyouwanttoassignspecificvaluestoheaderfieldsusedbyloadXMLNode,keepthefollowingpointsinmind:

Whenyouspecifythevalueofaheaderfield,youoverridewhateverdefaultvaluewebMethodsIntegrationServerisconfiguredtouseforHTTPrequests.Forexample,ifyousettheUserAgentheaderfieldtoB2B/3.0,theserverusesthatvalueinsteadofthedefaultvaluespecifiedbythewatt.net.userAgentparameter.

TheloadXMLNodeserviceautomaticallydeterminesthevalueoftheContentLengthheaderfield.YoucannotspecifyavalueforContentLength.

Beawarethatwhenyousubmitdatausingtheargsortableelements,loadXMLNodeautomaticallysetstheContentTypeheaderfieldtoapplication/x-www-form-urlencoded.Youcannotoverridethissettingusingtheheadersvariable.Ifyouwanttoexplicitlyspecifyacontenttypeinheaders,makesuretousethestringorbyteselementtosubmityourdata,notargsortable.

CertainheaderfieldsareautomaticallyderivedfromotherinputparametersassignedtoloadXMLNode.Forexample,theAuthorizationheaderfieldisautomaticallyderivedfromyourauthparametersetting.ExceptfortheContentLengthheaderfieldandtheContentTypeheaderfield(which,asdescribedabove,youcannotoverridewhensubmittingdataviaargsortable),avaluethatyouspecifyinheadersoverridesthevaluethatloadXMLNodemightotherwisederivefromotherparametersettings.

TheloadXMLNodeservicedoesnotvalidatedatathatyouspecifyinheaders.Itsimplypassesitontothetargetserverintherequestheader.Makesureyouspecifyheaderfieldnamesandtheirvaluescorrectly.Foracompletelistofvalidrequestheaderfields,seehttp://www.w3.orgforthelatestHTTPspecificationpublishedbytheW3C.

Tospecifyrequestheadersinheaders,createastringelementforeachheaderthatyouwanttospecify,where:

Thenameoftheelementdefinesthenameheaderfield(forexample,UserAgent,IfModifiedSince,Mail_Address),and

Thevalueoftheelementspecifiesthevalueyouwantassignedtothatfield.

Important! Inmostcases,thedefaultheadersthatloadXMLNodeusesareadequate.YoushouldnotaddorchangerequestheaderfieldsunlessyouarethoroughlyfamiliarwiththeHTTPprotocol.30 XML Services Developers Guide Version 7.1.1


ThefollowingproceduredescribeshowtousethePipelinetabtoassignvaluestoheadersinaflowservice.


2 InService In,selectheaders.

3 Click onthetoolbarandselectString.

4 Typethenameoftheheaderfieldthatyouwanttospecify.(YoudonotneedtotypeacolonafterthefieldnamebecauseloadXMLNodewillautomaticallyinsertthecolonwhenitinsertsthisfieldintotherequestheader.)

5 Click tomaketheelementachildofheaders.

6 Ifyouwanttohardcodethevalueofthiselement,dothefollowing:


b TypethevaluethatyouwantloadXMLNodetoassigntotheheadersfield.

c ClickOK.

7 Toassignthevalueofapipelinevariableforheaders,selectheadersandtheappropriatevariableinPipeline Inandthenclick tocreatealinkbetweenthem.

8 Repeatsteps 37foreachheaderfieldthatyouwanttosubmit.

The encoding variableYouusethisvariabletospecifythecharacterset(forexample,ISO88591)inwhichthereturneddocumentisencoded.Theparserusesthisvaluetoproperlyreadthetextinthedocument.

YoumaysetencodingtoautoDetectortothenameofaspecific,IANAregisteredcharacterset.WhenyousetencodingtoautoDetect,loadXMLNodesetsthecharactersetbasedonwhetherthedocumentcontainsXMLorHTML.Seethetablebelowfordefaults.

Toexplicitlyspecifyacharacterset,specifythenameofthatcharactersetinencoding.ValidcharactersetnamesarelistedintheInternetAssignedNumbersAuthority(IANA)charactersetregistry.

Ifyoudonotspecifyencoding,theparserassumesthefollowingdefaultsdependingonthetypeofdocumentitreceives:

To specify header fields in headers

If the document type is... encoding defaults to...

HTML ISO88591

XML UTF8XML Services Developers Guide Version 7.1.1 31


ThefollowingproceduredescribeshowtousethePipelinetabtoassignvaluestoencodinginaflowservice.


2 InService In,selectencoding.

3 Ifyouwanttohardcodethevalueofthiselement,dothefollowing:


b Typeoneofthefollowingintheencodingfield:

c ClickOK.

4 Toassignthevalueofapipelinevariableforencoding,selectencodingandtheappropriatevariableinPipeline Inandthenclick tocreatealinkbetweenthem.

The expandDTD variableYouusethisvariabletospecifywhetheryouwanttheloadXMLNodeservicetoexpandinstancesofnamedparameterentitiesinthereturneddocumentsDTD.IfyousetexpandDTDtotrue,loadXMLNodewillprocessparameterentityreferences,expandingthemtotheirfulldefinition.IfyousetexpandDTDtofalse,loadXMLNodeignoresparameterentityreferenceswhenitvalidatesthereturneddocument.

Youmaywantorneedtousethisvariableincaseswhenyouhaveasyntacticallycorrectdocumentthatcausesaparseerrorbecauseitviolatesadefinitioninanexternalparameterentityreference.BysettingexpandDTDtofalse,youcanbypasstheexternaldefinitionsothatloadXMLNodecanparsethedocumentsuccessfully.

To set the encoding value

Type... If you want the parser to...

autoDetect Decodethedocumentbasedonthedocumenttype.AssumesISO88591forHTMLdocumentsandUTF8forXMLdocuments.

The name of a registered IANA character set.

Decodethedocumentbasedonaspecifiedcharacterset.32 XML Services Developers Guide Version 7.1.1


IfyoudonotexplicitlysetexpandDTD,loadXMLNodesetsittofalse.


Usethe Set ValuemodifierinthePipelinetabandselectthevalueofexpandDTDfromthelist.

OR

Usethe LinkmodifiertoassignapipelinevariabletoexpandDTD.ThepipelinevariablemustsetexpandDTDtoavalueoftrueorfalse.(Thisvalueiscasesensitive.)

The isXML variableYouusethisvariabletospecifywhetherthedocumentyouwanttofetchcontainsHTMLorXML.Theserverrequiresthisvalueinordertoparsethecontentsofthedocumentcorrectly.

YoumaysetisXMLtoanyofthefollowingvalues:

IfyouknowwhattypeofdocumentloadXMLNodewillreceive,wesuggestthatyouexplicitlysetisXMLinsteadofusingautoDetect.Itwillcutprocessingtime,becausetheserverwillnothavetoexaminethedocumenttodetermineitstype.ThedefaultvalueisautoDetect.


Usethe Set ValuemodifierinthePipelinetabtoselectthevalueofisXMLfromthelist.

OR

Usethe LinkmodifiertoassignapipelinevariabletoisXML.ThepipelinevariablemustsetisXMLtoavalueofautoDetect,true,orfalse.(Thisvalueiscasesensitive.)

To set expandDTD in a flow service

Value Description

autoDetect Parsesthedocumentbasedonitsortag.Ifitcannotdeterminewhattypeofdocumentithas,itparsesitasanHTMLdocument.

false ParsesthereturneddocumentasHTML.true ParsesthereturneddocumentasXML.

To set isXML in a flow serviceXML Services Developers Guide Version 7.1.1 33


The loadAs variableYouusethisvariabletospecifythewayinwhichloadXMLNodepassestheparseddocumenttosubsequentservicesthatuseitasinput.

YoumaysetloadAstothefollowingvalues:

IfyoudonotexplicitlysetloadAs,loadXMLNodesetsittobytes.


Usethe Set ValuemodifierinthePipelinetabtoselectthevalueofloadAsfromthelist.

OR

Usethe LinkmodifiertoassignapipelinevariabletoloadAs.ThepipelinevariablemustsetloadAstoavalueofbytesorstream.(Thisvalueiscasesensitive.)

The failOnHTTPError variableYouusethisvariabletospecifywhethertheservicefails(throwsanexception)ifitreceivesanHTTPerrorasaresponse.Forexample,theservermightreturnanHTTP404NotFounderrorfortherequestedURL.YoumaysetfailOnHTTPErrortooneofthefollowingvalues:

Value Description

bytes Passestheparseddocumentasabytearray.YouusethissettingwhentheoutputfromloadXMLNodewillbeusedasinputtoaservicethatoperatesonwholedocuments(forexample,pub.xml:queryXMLNodeandpub.xml:xmlNodeToDocument).

stream Passestheparseddocumentasaninputstream.YouusethissettingwhentheoutputfromloadXMLNodewillbeusedasinputtoaservicethatcanincrementallyprocessadocument(forexample,pub.xml:getNodeIterator).

To set loadAs in a flow service

Value Description

false TheservicedoesnotfailbasedontheHTTPstatuscodereturnedbytheremoteserver.Thisisthedefaultvalue.

true TheservicefailsiftheremoteserverreturnsanHTTPerror.TheexceptionmessagecontainstheHTTPerrorcode,whichisdeterminedbytheW3CHTTPspecification.34 XML Services Developers Guide Version 7.1.1



Usethe Set ValuemodifierinthePipelinetabtoselectthevalueoffailOnHTTPErrorfromthelist.

OR

Usethe LinkmodifiertoassignapipelinevariabletofailOnHTTPError.ThepipelinevariablemustsetfailOnHTTPErrortoavalueoftrueorfalse.(Thisvalueiscasesensitive.)

Output Values from loadXMLNodeIfloadXMLNodeexecutessuccessfully,itproducesasingleoutput,anode,whichisanXMLnodecontainingtheparsedHTMLorXMLdocument.Youusenodeasinputtootherservicessuchaspub.xml:queryXMLNode(toextractspecificelementsfromthedocument)andpub.xml:xmlNodeToDocument(toextractallofthedocumentselements).

IfloadXMLNodeencountersanHTTPerrorduringexecution,theflowstepfailsandanexceptionisthrowniffailOnHTTPErrorissettotrue.Seethesectionthatfollows.

Error Handling With loadXMLNodeIfloadXMLNodefails,itreturnsanexception.IfloadXMLNodefailsbecauseofanHTTPerrorandfailOnHTTPErrorwassettotrue,thenitreturnsanexceptionwiththeHTTPerrorcode.

CommonreasonsforloadXMLNodetofailinclude:

urldoesnotbeginwithhttp:orhttps:. isXMListrue,butthedocumentcontainspoorlyformedHTML. Youhaveattemptedtoaccessaprotecteddocumentwithoutauthorization(thatis,

missingorincorrectuserauth/userand/orauth/passsettings).

loadXMLNodereceivesasyntacticallyincorrectdocumentthatcannotbeparsed. AnOutofMemoryerroroccurs. AnHTTPerror(forexample,theservercannotlocatetherequesteddocument)

occurs.

Anetworktimeoutoccurs. methodisnotGETorPOST. AnHTTPerror,suchas404filenotfoundoccurs.

To set failOnHTTPError in a flow serviceXML Services Developers Guide Version 7.1.1 35


Using the queryXMLNode ServiceYouusethepub.xml:queryXMLNodeservicetoselectivelyextractinformationfromaparsedHTMLorXMLdocumentandassignthatinformationtovariablesthatcanbelinkedtootherservices.

WhenyouusequeryXMLNode,youextractinformationusingeithertheXMLQueryLanguage(XQL)orthewebMethodsQueryLanguage(WQL).Bothlanguagesallowyoutoaddressandselectinformationfromanodebasedoncriteriathatyouspecifyinaquerystatement.

Passing a Node to queryXMLNodeThequeryXMLNodeservicetakesanodeasinput.WhenyouinvokequeryXMLNodeinaflowservice,youmusthaveanodevariable(containingparsedXMLorHTML)alreadyinthepipelineforqueryXMLNodetorunagainst.

ThereareseveralwaysinwhichyoucanproduceanodeforqueryXMLNodetorunagainst.

ThemeansthatyouusetoobtainanHTMLorXMLdocument,convertittoanode,andpassittothequeryXMLNodeserviceisadesigndecisionthatyoumustmakebeforeyoubeginbuildingyourflow.

If you want your service to... Create a flow service that...

FetchanXMLorHTMLdocumentfromaspecifiedURL.

1 Invokespub.xml:loadXMLNode(togetthedocumentfromtheWebandtransformittoanode),andthen

2 Invokespub.xml:queryXMLNode.QueryastringofrawHTMLorXMLthatisstoredinapipelinevariable.

1 Invokespub.xml:xmlStringToXMLNode(totransformthecontentsofthestringtoanode),andthen

2 Invokespub.xml:queryXMLNode.

QueryanXMLdocumentthatissubmitteddirectlytowebMethodsIntegrationServer.

1 Takesanodeasinput,andthen

2 Invokespub.xml:queryXMLNodeasthefirstserviceintheflow.

FordetailsonpostingXMLdirectlytoaservice,seeSubmittingandReceivingXMLviaHTTPonpage 13.36 XML Services Developers Guide Version 7.1.1


Addressing Information in a NodeWhenwebMethodsIntegrationServerparsesanHTMLorXMLdocument,ittransformsthedocumentintoatreelikestructurecontainingthedocumentsHTMLorXMLelements.Onceadocumentisparsed,youcanaddressindividualelementswithinitusinganXQLorWQLquery.

Forexample,inanHTMLdocument,youcouldusethefollowingquerytoextractthecontentsofthefirstparagraphinthedocument:

doc.p[0].text

InanXMLdocument,youmightuseanXQLquerythatlookslikethistoextractthephonenumberfromanelementcalledsupplierInfoinaSalesOrderdocument:

/SalesOrder[0]/supplierInfo[0]/phoneNum[0]/text()

ThequeryXMLNodeserviceallowsyoutouseeitherlanguagetodefineaquery.Italsoallowsyoutomakethischoiceonaquerybyquerybasis.Thatis,youcanextractsomeinformationfromthedocumentusingXQLandotherinformationwithWQL.

Thelanguagethatyouuseislargelydeterminedbypersonalchoiceandtheneedsofyourapplication.Eachlanguagehasafewspecificfeaturesthattheotherdoesnot.Whenyoubuildyourservice,youcantestyourqueriesusingeitherlanguagetodecidewhichprovidesthebetterresults.

ForadescriptionofWQL,seeAppendix A,webMethodsQueryLanguage. ForadescriptionofXQL,seeTheXMLQueryLanguage(XQL),at

http://www.w3.org/TandS/QL/QL98/pp/xql.html.

Working with a Sample DocumentTohelpyoubuildqueriesfasterandmoreaccurately,webMethodsDeveloperletsyougeneratequeriesbypointingtoanelementinasampledocument.Thesampledocumentthatyouuseshouldeitherbetheactualdocumentyourservicewillexecuteagainstatruntimeorarepresentativeexampleofthatdocument.

ToloadasampledocumentintoDeveloper,youexecuteyourflowintracemode(TestTrace).Whenyoudothis,DeveloperdisplaystheparseddocumentontheVariablestab.(TheVariablestabonlyappearswhenaqueryXMLNodeserviceisselectedintheeditor.)

Note: Althoughyoucandefinequerieswithoutloadingasampledocument,havingoneallowsyoutocreateyourqueriesfasterandmoreaccurately.XML Services Developers Guide Version 7.1.1 37


The XML Node View tab displays the elements of a document

TheVariablestabcontainstwoadditionaltabs:theXML Node ViewtabandtheSample Viewtab.

The XML Node View TabTheXML Node Viewtabshowsthenodes(addressablecomponents)thatarecontainedinadocument.Itallowsyoutobrowsethecontentsofadocumentandgeneratequeriesbypointingtothenodethatyouwanttoextract.

Developerusesthefollowingsymbolstodenotedifferenttypesofnodesinadocument:

Symbol Description

AnHTMLorXMLelement(e.g.,).Ifanelementcontainsadditionalnodes,the symbolappearsnexttoit.Clickthissymboltoviewadditionalnodeswithinanelement.

Anelementattribute(forexample,name=Intro).

Acomment.

After you runqueryXMLNode in

Trace mode, theparsed document

appears on the XMLNode View tab.38 XML Services Developers Guide Version 7.1.1


The Sample View TabTheSample Viewtabdisplaystheresultofaquery.Whenyoucreateaquery,DeveloperdynamicallyexecutesthatqueryagainstthesampledocumentanddisplaystheresultsontheSample Viewtab.

The Sample View tab displays the results of the selected query

Adding queryXMLNode to a Flow ServiceThefollowingproceduredescribesthestepsthatyouusetoinsert pub.xml:queryXMLNodeintoaflowservice.ThisprocedureassumesthatyouhaveaccesstoasampledocumentthatyoucanloadanddisplayinDeveloper.

Important! ThefollowingprocedureexplainshowtomanuallyinsertandspecifythequeryXMLNodeservice.Ifyouarebuildingaloadandquerysequence,youmaywanttousethewizardtobuildyourflowinstead.ItallowsyoutoquicklycreatealoadandqueryservicefromaURLthatyouspecify.Forinformationaboutusingthewizardtocreatealoadandqueryservice,seeLoadandQueryShortcutsonpage 61.

When you create aquery...

...you can view theresults on the

Sample View tab.XML Services Developers Guide Version 7.1.1 39


1 OpentheflowinwhichyouwanttoinsertthequeryXMLNodeservice.

2 Intheeditor,selectthepointwhereyouwanttoinvokequeryXMLNode,click intheeditortoolbar,andselectqueryXMLNodefromthelist.(IfqueryXMLNodedoesnotappearonthelist,clickBrowseandselectpub.xml:queryXMLNodefromthelistnexttoFolder.)

3 DooneofthefollowingtoloadyoursampleXMLorHTMLdocumentintoDeveloper:

IfyourflowpassesaparsedXMLorHTMLdocumenttoqueryXMLNodeviaaloadXMLNodeorxmlStringToXMLNodestep,selecttheTracecommandontheTestmenutoexecutetheflow.(MakesurethatthevariablesintheloadXMLNodeorxmlStringToXMLNodeservicearealreadycorrectlyspecifiedsothatitwillgeneratenodesuccessfully.)

IfyourflowexpectstheservertopassaparsedXMLdocumenttoit,selecttheSend XML FilecommandfromtheTestmenu,andthendothefollowing:

1 IntheSelect Test Modedialogbox,selectTraceandclickOK.

2 IntheSelect Filedialogbox,selectyoursampleXMLfileandclickOpen.

4 Whenthetracefinishesexecuting,selectthequeryXMLNodestepintheeditor,andthenselectXML Node ViewontheVariablestab.

5 Createaqueryforeachpieceofinformationthatyouwanttoextractfromthedocument.SeeSpecifyingaQueryonpage 41fordetailedprocedures.

6 Ifyouuseanamespaceprefixtoqualifyelementnamesinyourquery(forexample,/GSG:supplierInfo/name/text()),ANDyouwanttolinkthatprefixtoaspecificnamespaceinthedocument,usethefollowingproceduretoassigntheprefixtothedocumentsnamespace.(IfyoudonotusenamespaceprefixesinyourqueriesORtheprefixesyouusematchtheonesusedinthedocument,youcanskipthisstep.)

a ClickthePipelinetab.

b SelectthensDeclsvariableinService Inandclick onthetoolbartoopentheInput fordialogbox.

c Click andspecifythefollowing:

To insert queryXMLNode into a flow service

In this field... Specify...

Name Theprefixyouusetorepresentanamespaceinyourqueries.Value Thenamespacerepresentedbythisprefix.(Namespacesare

namedusingURLnotation.)40 XML Services Developers Guide Version 7.1.1


d ClickOK.

e Repeatsteps canddforeachnamespaceprefixthatyouneedtodefine.Whenyouarefinished,clickOKtoclosetheInput fordialogbox.

Specifying a QueryYouusetheVariablestabtodefinethequeriesthatqueryXMLNodewillexecutetopopulateasetofvariables.TheleftsideofthetabdisplaysthelistofvariablesthatyouwantqueryXMLNodetopopulate.Therightsideofthetabcontainsthecontrolsyouusetobuildaquerythatwillpopulateavariable.

Toexamineand/oreditthequeryforaparticularvariable,youselectthevariablefromthelistontheleftsideandviewand/oradjustthesettings(Query,Type,Allow Null,andsoforth)ontheright.

The Variables tab defines the variables that queryXMLNode will produce

This list displays theset of variables thatqueryXMLNode will

produce.XML Services Developers Guide Version 7.1.1 41


Therearetwowaysyoucandefineavariable(andthequerythatwillpopulateit)forqueryXMLNode:

YoucanmanuallytypethequeryintotheVariablestab.OR

Youcancreatethequerybypointingtothenodeyouwanttoextract.

Specifying a Query ManuallyIfyouarefamiliarwiththecontentsandstructureofthedocumentyouwanttoquery,youcanmanuallybuildaquerytoextractinformationfromit.Whenyoucreateaqueryinthisway,youdonotneedtoloadasampledocumentintoDeveloper(however,youmayeventuallywanttoloadonetotestyourqueriesandverifythattheyworkcorrectly).

ThefollowingproceduredescribeshowtomanuallycreateaninputvariableforthequeryXMLNodeserviceandassignaquerytoit.

1 IfthetoolbarontheVariablestabisnotactive,clickanywhereinthevariableslistbox(thewhiteareaontheleftsideofthetab)toactivateit.

2 Click onthetoolbartocreateanewvariableinthelist.

3 TypeanameforthevariableandpressENTER.

4 Setthefollowingoptions:

To manually create a variable for a queryXMLNode service

Set this option... To specify...

WQL/XQL Thelanguageinwhichyouwillwritethequery.

Set... To...

WQL UsethewebMethodsQueryLanguage.XQL UsetheXMLQueryLanguage.

Allow Nulls Whetheranullornonnullresultshouldcausetheservicetofailatruntime.

Set... If queryXMLNode should

Allow Null Acceptbothnullandnonnullresults.Fail if Null Issueanexceptionifthequeryproducesanull

result.

Fail if Not Null Issueanexceptionifthequeryproducesanythingbutanullresult.42 XML Services Developers Guide Version 7.1.1


5 IntheQueryfield,typeyourqueryandthenpressENTER.

DeveloperautomaticallyexecutesthequerywhenyoupressENTER.Ifyouhaveasampledocumentloaded,youcanclicktheSample Viewtabtodisplaytheresult.

Specifying a Query by Pointing to a NodeTocreatequeriesquicklyandaccurately,youcanselectanodeintheXML Node ViewtabandhaveDeveloperautomaticallybuildaquerythatselectsthetextforthatelement.AfterDeveloperbuildsthequery,youcanuseitasisoreditittosuityourneeds.

1 OntheXML Node Viewtab,selectthenodeforwhichyouwanttogenerateaquery.

2 RightclickandselectCreate New Variable from Node.

3 Typeanameforthevariablethatwillholdtheresultsofthequery,andpressENTER.

Type Thedatatypeofthevariableinwhichyouwantthequeryresultstored

Important! WhenqueryinganXMLdocument,makesuretotypenodenamesexactlyastheyarespecifiedinthedocument.ForXML,nodenamesarecasesensitive!(HTMLnodenamesarenot.)

\

Important! Tousethefollowingprocedure,youmustloadthesourcedocumentintheXML Node Viewtab.Ifyouhavenotalreadydonethis,runtheTestTracecommand(ifqueryXMLNodereceivesthenodefromaloadXMLNodeorxmlStringToXMLNodeservice)orTestSend XML File(ifqueryXMLNodereceivesinputdirectlyfromtheserver)beforeyoubegin.

Important! ThefollowingprocedureproducesaqueryinDevelopersdefaultquerylanguage.Toviewand/orchangeyourcurrentdefaultlanguage,ontheToolsmenu,clickOptions,clickIntegration Server,clickFlow Editor,andadjusttheDefault query language for queryXMLNodesetting.

To create a query from a node in the XML Node View tab

Set this option... To specify...XML Services Developers Guide Version 7.1.1 43


4 Setthefollowingoptions:

5 Ifnecessary,editthequeryintheQueryfield.PressENTERwhenyoufinisheditingtoreexecutethequery.Toviewtheresults,clicktheSample Viewtab.Foradditionalinformationaboutcreatingqueries,seeUsingWQLandXQLbelow.

Using WQL and XQLWQL(webMethodsQueryLanguage)isalanguagethatisusedtoretrieveinformationfromanHTMLorXMLdocument.WQLusesanobjectreferenceandanobjectpropertyinordertoextractdocumentelementsfromanHTMLorXMLdocument.Initssimplestform,thesyntaxisObjectreference.Objectproperty.Forexample,order[].text means:Selectthetextofallorderelementsinaparticularcontext(forexample,withinanXMLfile).

XQL(XMLQueryLanguage)isalanguagethatisusedtoretrieveinformationfromanXMLdocument.XQLusessimpledirectorynotation.Forexample,order/lineItemmeans:SelectalllineItemelementsinallorderelementsinaparticularcontext(forexample,withinanXMLfile).YoucanalsouseBooleanlogictofilteroutelements,selectallnodesofaparticularvalue,selectallnodeswithnodesinparticularranges,andsoforth.

Using WQL in a QueryAWQLqueryconsistsofoneormoreindexedelementarraysandanobjectproperty.Forexample,allofadocumentssnowboardproductelementsmaybecollectedintoanarraycalledsnowboard[],itsproductnamesmaybecollectedintoanarraycalledname[],itsproductpricesmaybecollectedintoanarraycalledprice[],andsoforth.

Set this option To specify...

Allow Null WhatqueryXMLNodeshoulddoifthequeryproducesanullresultatruntime.

Set If queryXMLNode should

Allow Null Acceptbothnullandnonnullresults.Fail if Null Issueanexceptionifthequeryproducesanull

result.

Fail if Not Null Issueanexceptionifthequeryproducesanythingbutanullresult.

Type Thedatatypeofthevariableinwhichyouwantthequeryresultstored.44 XML Services Developers Guide Version 7.1.1


Partial XML document

Thearraysareindexednumerically,beginningwith0.Toextractaparticularelement,youspecifyitsaddresswithinthearrayofwhichitisamember.Forexample,thefollowingistheWQLqueryforthefirstsnowboardelementinthepreviousexample:

doc.snowboard[0].text

Anobjectpropertyspecifiesthetypeofinformationthatyouwanttoextractfromthatelement.IntheWQLexampleabove,the.textsuffixspecifiesthatyouwanttoextractthetextcontainedwithindoc.snowboard[0].Thissuffixistheobjectproperty.ThispropertycaneitherbeoneofwebMethodspredefinedpropertiesoroneoftheelementsattributes(forexample,WIDTH,ALIGN,HREF).

webMethods Predefined Properties

WQLprovidesasetofpredefinedpropertiesthatyoucanusetoextractspecifickindsofinformationfromanelement.Forexample,togetthetextcontainedintheelementshownbelow:

Globe

Youusethe.textpropertyasfollows:doc.name[0].text

ThefollowingtabledescribesthesetofpredefinedpropertiesinthewebMethodsQueryLanguage.Notethateachpropertyhastwonames.ThisprovidesanalternativenameyoucanuseincaseswhereanelementhasanattributewiththesamenameastheWQL

GlobeFreeride/FreestyleA

14928.5279true

Pro SeriesFreeride/Powder/ExtremeB15628.9399false

XML Services Developers Guide Version 7.1.1 45


property(theattributenametakesprecedenceoveraWQLpropertynamewhenthetwonamesarethesame).

Use this property To get

.text

.txtThetextcontainedwithinthespecifiedelement.Ifthespecifiedelementcontainschildelements,thecontentsofallofthoseelementsareextractedtoo.

Example doc.name[0].textResult "Globe"

.value

.valThevaluecontainedwithinthespecifiedelement.Ifthespecifiedelementcontainschildelements,thevaluesforallofthoseelementsareextractedtoo.

Example doc.name[0].valueResult "Globe"

.source

.srcTheXMLorHTMLsourcecodeforthespecifiedelement.

Example doc.name[0].sourceResult Globe

.csource

.csrcTheXMLorHTMLsourcecodegeneratedfromtheparsetreeofthedocument.Thedifferencebetween.sourceand.csourcecanbethatsometagsandattributesofthesourcefilesaremodifiedtomatchthespecification.

Example doc.name[0].csource

ResultGlobe.index.idx

Theindexofthespecifiedelement.

Example doc.name[0].indexResult 0

.reference

.refThecompleteobjectreferenceforthespecifiedobject.

Example doc.name[0].referenceResult Doc.name[0]

.url TheURLofthedocument.

Example doc.urlResult http://www.AcmeCorp.com/documentArchive46 XML Services Developers Guide Version 7.1.1


Element Attributes

InadditiontothepredefinedpropertiesprovidedbythewebMethodsQueryLanguage,youcanalsospecifyanattributenameasaproperty.Whenyouspecifyanattributenameasaproperty,thequeryreturnsthevalueofthatattribute.Forexample,inthefollowingXMLelement:

Youwouldusethefollowingquery:doc.part[0].sku

ToextractthefollowingfromtheSKUattribute:"123456"

Specifying Multiple Elements

Toextractasingleitemfromadocument,specifyaquerythatextractsasinglememberofthatarrayasshowninthefollowingexamples:

Toextractmultiplemembersfromanobjectarray,youcanspecifythoseobjectsusingspecialindexnotationasshowninthefollowingexamples.

Foracompletedescriptionoftheindexvalueoptions,seeAppendix A,webMethodsQueryLanguage.

This reference Returns data from

doc.snowboard[0].text Thefirstsnowboardelementinthedocument.doc.snowboard[1].text Thesecondsnowboardelementinthedocument.doc.snowboard[5].text Thesixthsnowboardelementinthedocument.


doc.snowboard[ ].text Allsnowboardelementsinthedocument.doc.snowboard[1-10].text

Snowboardelements1through10inthedocument.

doc.snowboard[1-end] Snowboardelements1totheendofthedocument.doc.snowboard[1,3,7] Snowboardelements1,3,and7.doc.snowboard[1-3,5-7] Snowboardelements1,2,3,and5,6,7.doc.snowboard[2+2] Snowboardelements2,4,6,8XML Services Developers Guide Version 7.1.1 47


Nested Element References

Youcanspecifyanelementrelativetoanyoftheelementsitiscontainedwithin(thatis,relativetoitsparentcontainers).Forexample,thesecondproductnameelement(underscoredbelow)inthefollowingXMLfragment:

VertFreestyle/Pipe/ParkD15425479true

TraumaFreestyle/Pipe/ParkE15329.4367true

Canbereferencedineitherofthefollowingways:doc.name[1].textdoc.snowboard[1].name[0].text

Theindexvaluevaries,dependingonwhichparentelementsyouincludeinthereference.ThefirstcontainerinaWQLqueryisalwaysdoc,whichreferencesanode.

The Scope of a WQL Query

Nestedobjectreferencesalsodefinethescopeofaquery.Eachofthefollowingexamplesreferencesanelementcalledname[0],butbynestingelementsinthequery,youconstrainthescopeofthatquery.

For this query The scope is

doc.name[0].text Theentiredocument.doc.snowboard[0].name[0].text Thefirstsnowboardelementinthedocument.doc.bitterrootboards[2]. snowboard[0].name[0].text

Thefirstsnowboardelementwithinthethirdbitterrootboardselementinthedocument.48 XML Services Developers Guide Version 7.1.1


Referencing Data in Tables

ToretrievetheentirecontentsofatablewithinanHTMLdocument,specifythattablesindexvalue,anduse[]fortherowsandcolumnsinthattable.

doc.table[0].tr[].td[].text

Besidestablereferences,otherqueriescancreateatableasaresult.Forexample,thefollowingquerygetsallboldtextfromalllistitemsinanHTMLdocument:

doc.ul[0].li[].b[].text

Itsresultmaybeoneormorebolditemsfromeachlistitem.Toholdthistypeofoutput,thevariablemustalsobeaStringTable.

Using Search Strings as Index Values

Youcanusepatternmatchingstringsinsteadofindexnumberstoselectmembersofanelementarray.Thistypeofqueryreturnsdatafromthoseelementswhosetextpropertymatchesthespecifiedpatternmatchingstring.Forexample,thefollowingquery:

doc.bitterrootboards['*Pro Series*'].text

ReturnseverybitterrootboardselementthatcontainsthestringProSeriesanywherewithinit.

Wildcard Symbols

Patternmatchingstringsusedinplaceofanindexvaluecanincludethefollowingwildcards:

Note: Referencesthatcombinemorethantwoarraysarecollapsedintotwodimensionaltables.

Use this symbol To

* Matchanysequenceofzeroormorecharacters.

? Matchanysinglecharacter.

% Matchasingleword(thatis,asequenceofnonwhitespacecharacters).

\ Escapetheabovemetacharacters.

ExampleYouwanttoreturnallbitterrootboardselementsthatcontainthecharacter?.Youusethefollowingquery:

doc.bitterrootboards['\?'].text

Note: Matchstringsarecasesensitive.XML Services Developers Guide Version 7.1.1 49


Examples

Regular Expressions as Index Values

AsanalternativetousingwebMethodsstandardpatternmatchingsyntaxdescribedabove,youcanusearegularexpressiontospecifyapatternmatchingstring.Whenyouusethismethod,youenclosetheregularexpressionin/charactersasshowninthefollowingexample:

doc.bitterrootboards[/*Pro Series*/].text

ThisexamplewillreturneverybitterrootboardselementthatcontainsthestringProSeriesanywherewithinit.Forinformationaboutregularexpressions,seethewebMethodsDeveloperUsersGuide.

Attribute Matching

Bydefault,matchstringsarecomparedwiththe.textpropertyofthespecifiedelements;however,youcanmatchonotherpropertiesbyspecifyingthatpropertyandamatchstringasshowninthefollowingexample.

doc.a(HREF='*webmethods.com*').src

Thisexampleextractsallhypertextlinksto*webmethods.com*.

This reference Returns

doc.name['*fourth*'].text Thetextfromallnameelementscontainingthestringfourth.

doc.name['*fourth*'].src Thesourcecodefromallnameelementscontainingthestringfourth.

doc.tr['199? *'].idx Theindexofeveryrowthatcontainsastringbeginningwith199followedbyanycharacterandaspace.

doc.table['*sku*'].tr[].text Thetextfromeveryrowofanytablecontainingthestringsku.

doc.tr['*Green*'].td[1].idx ThetextfromthesecondcellofanytablerowcontainingthestringGreen.

doc.table[1].tr['*Green*'].td[1].text

ThetextfromthesecondcellofanyrowcontainingthestringGreeninthesecondtable.

doc.tr['*H????*Red*'].td[1].text ThetextfromthesecondcellofanyrowthatcontainsastringbeginningwithHseparatedbyatleast4charactersfromastringthatbeginswithRed.

Important! Whenyouwanttosearchaspecificproperty,youmustenclosethepropertyassignmentstatementinparentheses,notbrackets.50 XML Services Developers Guide Version 7.1.1


Matching on the Name Attribute

ElementsthatcontainaNAMEattributecanbereferenceddirectlybyname.Forexample,togetthetextfromallelementshavingthenamesku,youwouldusethefollowingreference:

doc.sku.text

Togetthetextfromalltablecellshavingawidthvalueof8%fromallelementsnamedsku,youwouldusethefollowing:

doc.sku.td(width='8%').text

Using Masks to Extract Data

Whenyouspecifyaquery,thatqueryreturnsthecompletecontentsofthespecifiedproperty.Forexample,thefollowingquery:

doc.snowboard[1].text

Returnsallofthetextfromthespecifiedsnowboardelement.Ifyouwanttoextractonlyaportionofthereturnedtext,youcanapplyamasktothetextpropertytoeliminateunwantedinformation.Forexample,thefollowingobjectreference:

doc.snowboard[1].text['&list*']

Eliminatesthewordlistandeverycharacterthatfollowsit.

Thefollowingtabledescribesthesymbolsyouusetoconstructamask:

Amaskpatternismatchedagainstthetextofanobjectreferenceuntilthepatternisexhausted,andanyremainingcharacterswillbeincludedintheresult.

Use this symbol To

? Eliminateasinglecharacterfromtheresult.

* Eliminateastringcontaininganycharacters.

% Eliminateasingleword(thatis,asequenceofnonwhitespacecharacters).

$ Collectasinglewordandincludeitintheresult.

& Collectastringcontaininganycharactersandincludethatstringintheresult.

\ Escapetheabovemetacharacters.

ExampleYouwanttoreturnthetextofallsnowboardelementsinthedocument,eliminatingallasterisks(*)fromtheresults.Youusethefollowingquery:

doc.snowboard[].text['\*']XML Services Developers Guide Version 7.1.1 51


Examples

Regular Expressions in a Mask

AsanalternativetousingwebMethodsstandardmasksyntaxdescribedabove,youcanusearegularexpressiontospecifyamask.Whenyouusethismethod,youenclosetheregularexpressionin/charactersasshowninthefollowingexample:

doc.snowboard[1].text[/.list*/]

Thisexamplewilleliminatethewordlistandeverycharacterthatfollowsitfromtheresult.Forinformationaboutregularexpressions,seethewebMethodsDeveloperUsersGuide.

Using Lines to Select Data

Ifanelementcontainstags,youcanaddresseachlineofthatelementindividuallyusingtheline[]array.Forexample,toreferencethethirdlineinthefollowingparagraph:

The current balance for customer account1001-233is $14,009.50as of 14:04pm 10/16/98.

Youcanusethefollowingquery:doc.p[0].line[2].text

Youcanalsoreferencelinesoftextwithinaelementinthesameway.Forexample,togetthesecondlineinthefollowingsegmentofpreformattedtext:

ITEM DESC QTY UPRICE TOTAL06-5449 1 ITC Casing 250 .43 $ 107.50010-13 #4 PVC Line 50 23.50 $1175.0000901R Tak Connector 25 3.50 $ 87.50

Youusethefollowingquery:doc.pre[0].line[1].text

This mask Performs the following

.text['&list*'] Keepsallcharactersupto(butexcluding)thestringlist,andtheneliminatestherest.

.text['%%%&'] Eliminatesthefirstthreewordsintheresultandkeepstheremainingcharacters.

.text['*page&how*'] Eliminatesallcharactersupto(andincluding)thestringpage;keepsallcharactersupto(butexcluding)thestringhow;andeliminatestherest.52 XML Services Developers Guide Version 7.1.1


Likeotherelements,youcanusenumericrangesorpatternmatchingstringsastheindextothelinearray.

Examples

Using Character Ranges to Extract Data

Youcanuseaspecialtypeofpropertymasktoreturnaspecificrangeofcharactersfromaresult.Forexample,thefollowingqueryextractsonlythefirst10charactersfromthesecondnameelement:

doc.name[1].text[0-9]

Thecombinationofcharacterrangesandlinearrayallowsyoutocreateverycomplexqueriesandgivesyoutremendousflexibilityingettingspecificdatafromtextobjects.Forexample,thefollowingquery:

doc.pre[0].line[*connector*].text[43-50]

Getsthetextfromcolumns43through50ofanylineinthefirstpreformattedelementcontainingthestringconnector.

Using XQL in a QueryDataparsedfromanXMLdocumentcanbeaccessedwithaXQLquery,whichconsistsofbasicURIsyntaxthatspecifieselementsintheXMLtree.Forexample,thefollowingspecifiesthecollectionofpoNumelementswithinSalesOrderelements,assumingthattherootelementofthedocumentisSalesOrder:

/SalesOrder/poNum

Thecollectionofallelementswithacertaintagnameisexpressedusingthetagnameitself.Thiscanbefurtherqualifiedbyindicatingthatthescopeisthecurrentcontext/,butthecurrentcontextisassumedandneednotbenotedexplicitly.

Example

ToselectallpoNumelements,thefollowingareequivalent:/poNumpoNum


doc.p[0].line[].text Alllinesoftextinthefirstparagraph.doc.p[0].line[1].text Thesecondlineoftextinthefirstparagraph.doc.p[0].line['*demo*'].text Alllinesoftextinthefirstparagraphthat

containsthestringdemo.doc.pre[0].line[2,8].text Lines3and9fromthefirstpreformattedtext

elementinthedocument.doc.pre[0].line[0+5].text Everyfifthlineoftextfromthefirstpreformatted

textelementinthedocument.XML Services Developers Guide Version 7.1.1 53


Specifying a Method in XQL

XQLprovidesasetofpredefinedmethodsthatyoucanusetoextractspecifickindsofinformationfromanelement.Forexample,togetthetextcontainedinthefirstelementinthefollowingexample:

GSG-99401088

Youusethetext()methodasfollows:/SalesOrder/poNum[0]/text()

ThefollowingtabledescribesthesetofpredefinedmethodsinXMLQueryLanguage.

Use this method To get

text() Thetextcontainedwithinthespecifiedelement,minusanywhitespacesuchasspaces,tabs,andlinebreaks.Ifthespecifiedelementcontainschildelements,thecontentsofallofthoseelementsareextractedtoo.

Example /SalesOrder/poNum[0]/text()Result "GSG-99401088"

rawtext() Thetextcontainedwithinthespecifiedelement,includinganywhitespace.

Example If/SalesOrder/poNum[0]contains" GSG-99401088",theinitialthreespacesareretainedintheresult.

value() Thevaluecontainedwithinthespecifiedelement.Ifthespecifiedelementcontainschildelements,thevaluesforallofthoseelementsareextractedtoo.

Example /SalesOrder/poNum[0]/value()Result "GSG-99401088"

float() Thevaluecontainedwithinthespecifiedelement,returnedasafloatingdecimal.Thismethodisusefulincomparisons.SeeSpecifyingElementswithComparisonOperatorsonpage 59.

integer() Thevaluecontainedwithinthespecifiedelement,returnedasaninteger.Thismethodisusefulincomparisons.SeeSpecifyingElementswithComparisonOperatorsonpage 59.

index() Theindexnumberofthenodewithintheparent.

Example /SalesOrder/poNum[0]/index()Result 054 XML Services Developers Guide Version 7.1.1


Element Attributes

InadditiontothepredefinedmethodsprovidedbyXQL,youcanalsospecifyanattributenameinaquery.Whenyouspecifythe@characterandanattributename,thequeryreturnsthevalueofthatattribute.Forexample,inthefollowingXMLelement:

nodeType() Thenumberthatindicatesthetypeofnode.

Example /SalesOrder/poNum[0]/nodeType()Result1

Number Node Type

1 Element

2 Attribute

3 Text

7 PI

8 Comment

9 Documentnamespace() TheURIforthenamespaceofthenode.

Example/SalesOrder/poNum[0]/namespace()Resulthttp://www.AcmeCorp.com/documentArchive

baseName() Thenameportionofthenode,excludingtheprefix.

Example /SalesOrder/poNum[0]/baseName()Result poNum

prefix() Theprefixforthenode.

Example /SalesOrder/poNum[0]/prefix()Result AcmeCorp(thevariableinthexmlnsstatementofthedocument)

end() Trueifthenodeisthelastinthecollection,relativetotheparentnode.Nulliftheindexvalueisoutofrange.

Example /SalesOrder/poNum[0]/end()Result true

Example /SalesOrder/poNum[10]/end()Result null

Use this method To getXML Services Developers Guide Version 7.1.1 55


Youwouldusethefollowingquery:part[0]/@sku

ToextractthefollowingfromtheSKUattribute:"123456"

Ifyouwanttoextractallvaluesofallattributeswithinanelement,youusetheat(@)andasterisk(*)wildcardcharacters.ThisisusefulifyouwanttotreatattributesasfieldsinaDocument.Forexample,inthefollowingXMLelement:

Youwouldusethefollowingquery:part[0]/@*

Toextractthefollowingfromthepartelement:"Widget" "123456" "5000"

Specifying Multiple Elements

ToextractmultipleelementsfromanXMLdocument,youcanspecifythosenodesusingspecialindexnotationasshowninthefollowingexamples.Ifyoudonotspecifyanindexnumber,thequeryreturnsallelements.

Nested Element References

Youcanspecifyanelementrelativetoanyoftheelementsitiscontainedwithin(thatis,relativetoitsparentcontainers).Forexample,thesecondcompanyNameelement(underscoredbelow)inthefollowingXMLfragment:

Important! Attributescannothavepathoperatorsnorindicesappendedtotheminaquery.Suchquerieswillresultinsyntaxerrors.

This query Returns data from

vendorNum/text( ) AllvendorNumelementsinthedocument.vendorNum[0 $to$ 2]/text( ) ThefirstthreevendorNumelementsinthe

document.vendorNum[1,3,7]/text( ) vendorNumelements1,3,and7.56 XML Services Developers Guide Version 7.1.1


Partial XML document

Canbereferencedineitherofthefollowingways://companyName[1]/text()//supplierInfo[0]/companyName[0]/text()

Theindexvaluevaries,dependingonwhichparentelementsyouincludeinthereference.

Thefirstseveralcharactersarepathoperators.Youusetheseoperatorstodrilldownlevelsinthedocumentyouarequerying.The/operatorbeforeanelementindicatesthe

Global Sporting GoodsGSG-970414-0A(216) 741-7566(216) 741-7533

10211 Brookpark Rd

ClevelandOH22130

[email protected] Wielman

Bitterroot Boards, LLC8444 99731 Q64500(406) 721-5000(406) 721-5001

Suite 4411290 Antelope DrMissoulaMT59801 1290

[email protected] Norgaard

BK-XS160Extreme Spline 160 Snowboard- Black

10149.0014900.00

XML Ser

7-1-1 xml services developers guide

Documents

xml documents9overview

xml services developers

xml node view tab

method variable

loadxmlnode service

query services

failonhttperror variable

loadas variable