7-1-1 XML Services Developers Guide

TitlePage
XML Services
Developers Guide
Version 7.1.1
January 2008
webMethods
Copyright & Docu mentID
ThisdocumentappliestowebMethodsIntegrationServerVersion 7.1.1andwebMethodsDeveloperVersion 7.1.1andtoallsubsequent releases. Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions. CopyrightSoftwareAG2008. Allrightsreserved. ThenameSoftwareAGand/orallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.Other companyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners. Document ID: DEV-XML-DG-711-20080128
Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Submitting and Receiving XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Receiving XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTPing a File from a webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Sending XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Using the Load and Query Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Are the Load and Query Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Parsing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Node? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Query? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the loadXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding loadXMLNode to a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input and Output Values for loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inputs for loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The url variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The method variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The auth variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The data variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The headers variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The encoding variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The expandDTD variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The isXML variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7 7 9 10 10 10 11 11 11 13 13 14 14 15 16 16 17 17 17 18 19 20 20 20 20 20 21 21 22 22 22 23 24 25 30 31 32 33
XML Services Developers Guide Version 7.1.1
Table of Contents
The loadAs variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The failOnHTTPError variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output Values from loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Handling With loadXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the queryXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing a Node to queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Information in a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with a Sample Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The XML Node View Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Sample View Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding queryXMLNode to a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Query Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Query by Pointing to a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using WQL and XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using WQL in a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Predefined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Multiple Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nested Element References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Scope of a WQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Data in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Search Strings as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcard Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expressions as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attribute Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Matching on the Name Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Masks to Extract Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expressions in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Lines to Select Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Character Ranges to Extract Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using XQL in a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Method in XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Multiple Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nested Element References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Search Strings as Index Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Elements with Particular Namespaces . . . . . . . . . . . . . . . . . . . . . Specifying Elements with Boolean Expressions . . . . . . . . . . . . . . . . . . . . . . . Specifying Elements with Comparison Operators . . . . . . . . . . . . . . . . . . . . . Quick Reference: WQL vs. XQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output from queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Errors from queryXMLNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
34 34 35 35 36 36 37 37 38 39 39 41 42 43 44 44 45 47 47 48 48 49 49 49 50 50 51 51 52 52 53 53 54 55 56 56 58 59 59 59 60 61 61
Table of Contents
Load and Query Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Default Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Load and Query Service from a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A. webMethods Query Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sibling Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
61 61 62 65 66 66 68 69 70 71
Table of Contents
About This Guide

ThisguideisforuserswhowanttosubmitandreceiveXMLdocumentswith webMethodsDeveloper,convertXMLdocumentstoISdocuments(andviceversa),and queryXMLdocumentsusingXQLorWQL.
Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchangebased onyourspecificsituationorenvironment.Identifiestermsthefirst timetheyaredefinedintext.Alsoidentifiesserviceinputandoutput variables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously arejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.
Narrow font
Typewriter font
UPPERCASE \ [ ]
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovides youwithimportantsourcesofinformationaboutwebMethodsproducts: Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides troubleshootinginformationformanywebMethodsproducts. Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto theDocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe documentationduringproductinstallationtoasingledirectorycalled _documentation,locatedbydefaultunderthewebMethodsinstallationdirectory. Inaddition,youcanfinddocumentationforallwebMethodsproductsonthe webMethodsBookshelf.
About This Guide
Submitting and Receiving XML Documents

10 10 11 13 14 17
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 Submitting and Receiving XML Documents
Overview
YoucansubmitXMLdocumentstothewebMethodsIntegrationServerfromaclient, andhavetheIntegrationServerreceiveXMLdocumentswithservicesthatyouwrite.The IntegrationServerprovidesthefollowingautomatedmechanismsforreceivingarbitrary XMLdocuments,parsingthem,andpassingthemasinputtoaspecifiedservice. AclientsubmitsanXMLdocumenttoaserviceinaStringvariable(ofanyname), whichthetargetserviceconvertsintoanodeusingpub.xml:xmlStringToXMLNode. AclientsubmitsanXMLdocumenttoaserviceinaspecialStringvariablenamed $xmldata,andwebMethodsIntegrationServerautomaticallyparsesthevariableand passesittotheserviceasanode. AclientpostsanXMLdocumenttoaserviceviaHTTP. AclientFTPsanXMLdocumenttoaservice. AclientemailsanXMLdocumenttoaservice. AclientsendstheXMLdocumentasanemailattachment.
Submitting and Receiving XML in a String Variable

OnewaytosubmitanXMLdocumenttothewebMethodsIntegrationServeristopass theentireXMLdocumenttoaserviceinaStringvariable.Whenyouusethisapproach, youshouldcodethetargetservicetoexecutepub.xml:xmlStringToXMLNodetoconvertthe Stringvariable(thatis,theXMLdocument)toanode.OncetheXMLdocumentis representedasanode,itexistsinaformthatcanbequeriedorconvertedtoanIData object.ForinformationaboutusingxmlStringToXMLNode,seethewebMethodsIntegration ServerBuiltInServicesReference.
Example: Submitting XML in a String

ThefollowingcodefragmentshowshowaJavaclientmightsubmitanXMLdocumentto aservicecalledpurch:postOrderonwebMethodsIntegrationServer.Inthisexample,the client: 1 2 3 LoadstheXMLdocumentintoaString PutstheStringintotheelementordersinanIDataobjectnamedinputs Invokespurch:postOrderontheserveratlocalhost:5555
10
import import import import public
com.wm.app.b2b.client.*; com.wm.util.*; com.wm.data.*; java.io.*; 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(); . . .
Example: Receiving XML in a String

Ontheserver,thereceivingserviceshouldbecodedtopasstheXMLintheString variabletopub.xml:xmlStringToXMLNode.Thisproducesanodethatcanbesubsequently queriedorconvertedtoanIDataobject. Inthepreviousexample,purch:postOrdershouldbecodedtopasstheXMLdocumentin orderstopub.xml:xmlStringToXMLNode.Forinformationabouttheservicesthatyoucanuseto manipulatenodes,seepub.xml:queryXMLNodeandpub.xml:xmlNodeToDocumentinthe webMethodsIntegrationServerBuiltInServicesReference.
Submitting and Receiving XML in $xmldata

SubmittinganXMLdocumenttowebMethodsIntegrationServerusing$xmldatais similartosubmittingitasaStringvariable,butinthiscase,theservicereceivingtheXML documentdoesnotneedtoincludeaparsingstep;webMethodsIntegrationServer automaticallyparsesthecontentsof$xmldata. Thename$xmldatahasspecialmeaningtotheIntegrationServerinthatitassumesthe valueofthisvariableisanXMLdocument.Whenitreceivesarequestthatincludesan inputvariablenamed$xmldata,theserverautomaticallyparsesthecontentsofthat variable,producinganXMLnodethatcanbeusedbyanyservicethattakesanodeas input.
Example: Submitting and Receiving XML in $xmldata

ThefollowingexampleshowsaclientapplicationthatreadsanXMLdocumentfroma file,assignsthetextinthefileto$xmldataandthenpasses$xmldatatoaservicecalled sales:getOrder.
11
import import import import
com.wm.app.b2b.client.*; com.wm.util.*; com.wm.data.*; 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); }
Theserviceinvokedbythisclientmustbeaservicethattakesanodeasaninputvariable (forexample,queryXMLNode,xmlNodeToDocument),becausethisiswhatwebMethods IntegrationServerproduceswhenitreceivesthisrequest. Important! ThisexampleshowsaJavabasedclient;however,anytypeofISclient(even abrowserbasedclient)canbeused.Withabrowserbasedclient,youwouldpostthe XMLdocumentasthevalueportionofa$xmldata=valuepair.Youwouldmostlikely constructtheXMLdocumentwithJavascript.Youmaypostothername=valuepairs withtherequest.
12
Submitting and Receiving XML via HTTP

AclientcanpostanXMLdocumenttoaservicethatreceivesitviaHTTP.Tousethis approach,youmusthaveaclientthatcan: Sendastringofdata(anXMLdocument)towebMethodsIntegrationServerusingthe HTTPPOSTmethod. AND SetthevalueoftheContent-Typerequestheaderfieldtotext/xml. WhenwebMethodsIntegrationServerreceivesanHTTPPOSTrequestwhereContentTypeistext/xml,itautomaticallyparsesthebodyoftherequest(theXMLdocument)and passesitasanodetotheservicespecifiedintherequestsURL.
Client Requirements
SincemostbrowsersdonotallowyoutomodifytheContentTypeheaderfield,theyare notsuitableclientsforthistypeofsubmission.Clientsthatyoumightusetosubmitan XMLdocumentinthismannerarePERLscripts(whichallowsyoutobuildandissue HTTPrequests)orthewebMethodsIntegrationServerservice,pub.client:http. Regardlessofwhichclientyouuse,itmustdothefollowing: SubmitaPOSTrequesttowebMethodsIntegrationServer. AddresstherequesttotheURLofanservice(forexample, http://rubicon:5555/invoke/purch/postOrder). SettheContentTypeheaderfieldtotext/xml. ContainanXMLdocumentinthebodyofthemessage.Thedocumentmustbethe onlytextthatappearsinthebodyoftherequest.Donotassignittoaname=value pair. Important! WhenyousubmittheXMLdocument,placeanextracarriagereturn/new line(\r\n)attheendofittoindicatetheendoftheXMLdocument.
13
Example: Submitting and Receiving XML via HTTP

Thefollowingexampledescribesthevaluesthatyousetifyouusepub.client:httptoPOST anXMLdocumenttoaservice. Set this variable... url To... TheURLoftheservicethatyouwanttoinvoke.Thefollowing valuewouldinvokethe purch:postOrderservicefromaserver namedrubiconwithportnumber5555. Example http://rubicon:5555/invoke/purch/postOrder method headers.ContentType data.string OR data.bytes YouwillalsosetanyoptionalHTTPparameters,suchasauthorizationinformation,that arerequiredbyyourapplication.
post text/xml
TheXMLdocumentthatyouwanttopost.
Submitting and Receiving XML via FTP

YoucanFTPanXMLdocumenttowebMethodsIntegrationServersFTPlisteningport. (BydefaulttheFTPportisassignedtoport8021.However,thisassignmentis configurable,soyoushouldcheckwithyourwebMethodsIntegrationServer administratortoseewhichportisusedforFTPcommunicationsonyourwebMethods IntegrationServer.) WhenaclientputsafileontheIntegrationServerforthepurposeofinvokingaservice, theFTPListenerwillchooseacontenthandler,basedonthefileextension,toconvertthe filecontentintotheinputvaluesfortheservicetoinvoke.TheIntegrationServers lib/mime.typesfilecontainsthemappingoffileextensiontocontenttype. Tip! Youcaneditthemappingsinthelib/mime.typesfile(andreloaditwithout restartingIntegrationServer),byselectingSettings > Resources > Mime Typesfromthe IntegrationServerAdministratorscreen. WhentheIntegrationServerreceivesanXMLdocumentontheFTPlisteningport,it automaticallyparsesthedocumentandpassesitasanodetotheserviceinthedirectory wherethefilewasFTPed.
14
TosubmitanXMLdocumenttowebMethodsIntegrationServerviaFTP: TheXMLdocumentcanbecontainedinafilethathaseither:

Afileextensionofxml Afileextensionwhosemimetypeisregisteredwiththeserverastext/xml. Todothis,edittheIntegrationServerslib/mime.typesfile.Forexample:

text/xml mimetype
Nofileextension Toconfigureacontenthandlertohandlefilesthathavenoextension,usethe specialkeyftp_no_extensioninthelib/mime.typesfiletoindicateanull extension.Then,specifythecontenttypemappedtoanullextension.For example,thefollowingXMLcontenthandlerisusedtohandlefileswithoutan extension:

text/xml ftp_no_extension
Ifyouwanttouseadifferentkeytospecifyanullextension,usetheproperty watt.net.ftp.noExtensionKeytospecifythekeyusedinlib/mime.typesto specifyafilewithnoextension.Thedefaultvalueofthispropertyis ftp_no_extension. Theservicetowhichyouwanttopassthedocumentmusttakeanodeasinput.
Client Requirements
IfyouwanttosubmitanXMLdocumenttoaservicethroughFTP,theapplication sendingthedocumentmustdothefollowing: 1 2 InitiateanFTPsessiononwebMethodsIntegrationServersFTPlisteningport. PointtothedirectorythatcontainstheservicetowhichyouwanttopasstheXML document. Example cd \ns\Purchasing\SubmitOrder Important! NotethattherootdirectoryforthisoperationisyourwebMethods IntegrationServersnamespacedirectory(ns),nottherootdirectoryofthetarget machine.Therefore,ifyouwanttoFTPafiletoaserviceinthePurchasingpackage, youuse\ns\Purchasing\ServiceNameasthepathtothatservice,not IntegrationServer_directory\ns\Purchasing\ServiceName. 3 CopytheXMLdocumenttothisdirectoryusingthefollowingcommand:
put XMLDoc.xml
or
put XMLDoc
WhereXMLDocisthenameofthefilethatyouwanttopasstowebMethods IntegrationServer.Thefileextensioncanbesomethingotherthanxmlifthe
15
extensionsmimetypeisregisteredwiththeserverastext/xml.Alternatively,thefile extensioncanbeomittedifyouspecifythespecialkeyftp_no_extensioninthe lib/mime.typesfiletoindicateanullextension.SeeSubmittingandReceivingXML viaFTPonpage 14fordetails. Example put PurchaseOrder.xml NotethattheXMLdocumentyouFTPtowebMethodsIntegrationServerisnever actuallywrittentotheserversfilesystem.TheXMLdocumentyousendandthe outputfileitproduces(seebelow),arewrittentoavirtualdirectorysystem maintainedinyourISsession.
FTPing a File from a webMethods Integration Server

Thepub.clientfoldercontainsbuiltinservicesyoucanusetoFTPafilefromawebMethods IntegrationServer.Forinformationabouttheseservices,seethewebMethodsIntegration ServerBuiltInServicesReference.
Receiving XML via FTP

TheresultsfromaserviceexecutedbyanFTPrequestarewrittentothesamevirtual directorywheretheXMLdocumentwasinitiallyFTPed. Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresults(thatis,the contentsofthepipeline)areXMLencodedandreturnedasanXMLdocument. IftheservicehasanXMLoutputtemplateassignedtoit,thattemplateisappliedto theresults.(IfthetemplateisnotanXMLbasedtemplate,itisnotapplied.) Thenameoftheoutputfiletowhichresultsarewrittenis:
XMLDoc.xml.out
WhereXMLDoc.xmlisthenameoftheXMLfileinitiallyFTPedtotheservice.(Thefile extensioncanbesomethingotherthanxmliftheextensionsmimetypeisregistered withtheserverastext/xml.) YouretrievethisXMLdocumentusingtheFTPgetcommand.Forexample,ifyouput anXMLdocumentcalledPurchaseOrder.xmlonwebMethodsIntegrationServer,youwould usethefollowingFTPcommandtogetitsresults: Example get PurchaseOrder.xml.out Important! WerecommendthatyouuseauniquenameforeachXMLdocumentthat youFTPtowebMethodsIntegrationServer(perhapsbyattachingatimestamptothe name)sothatyoudonotinadvertentlyoverwriteotherFTPedXMLdocumentsor theirresultsduringanFTPsession. WhenyouendtheFTPsession,webMethodsIntegrationServerautomaticallydeletesthe originalfileanditsresultsfromyoursession.
16
Submitting and Receiving XML via E-mail

YoucanemailanXMLdocumenttoanemailmailboxandhavewebMethods IntegrationServerautomaticallyretrievetheemailmessageandprocesstheXML documentitcontains.Todothis,yourwebMethodsIntegrationServermustbe configuredwithanemailportthatmonitorsthemailboxtowhichtheXMLdocument willbesent.(ConsultyourwebMethodsIntegrationServeradministratortoseewhether anemailporthasbeensetuponyourwebMethodsIntegrationServer.) WhenanXMLdocumentarrivesintheemailportsmailbox,webMethodsIntegration Serverautomaticallyretrievesthemessage,parsestheattachedXMLdocument,and passestheXMLdocumentasanodetotheservicespecifiedontheemailssubjectline (or,ifaserviceisnotspecifiedonthesubjectline,theemailportsdefaultservice).
Client Requirements
TosubmitanXMLdocumenttowebMethodsIntegrationServerviaemail,yourclient programmust: PuttheXMLdocumentinanemailattachment. SettheemailsContent-Typeheadertotext/xml. SpecifythenameoftheservicethatwillprocesstheXMLdocumentintheemails subjectline.Ifyouleavethesubjectlineempty,theXMLdocumentwillbeprocessed bytheglobalserviceifoneisdefinedor,ifnot,bythedefaultserviceassignedtothe emailport(ifonehasbeenassigned).Forinformationaboutspecifyingtheports defaultservice,seethewebMethodsIntegrationServerAdministratorsGuide. TheservicethatprocessestheXMLdocumentmusttakeanodeasinput.
Example: Sending XML via E-mail

Thefollowingexampledescribesthevaluesthatyouwouldsetifyouusedpub.client:smtp toemailanXMLdocumenttoaservice.(Formoreinformationaboutusingthisservice, seethewebMethodsIntegrationServerBuiltInServicesReference.) Set this variable... to subject To... AStringspecifyingtheemailaddressthatwebMethods IntegrationServersemailportmonitors. AStringspecifyingthefullyqualifiednameoftheservice thatwebMethodsIntegrationServerpassestheattached XMLdocumentto. Example: orders:ProcessPO Ifyoudonotspecifysubject,theemailportwillinvokeits defaultservice(ifonehasbeenassignedtoit).
17
Set this variable... from body
To... AStringcontainingtheemailaddresstowhichtheresults oftheservicearesent. AStringcontaininginputparametersfortheserviceinURL querystringformat.Thefollowingexamplesetsfive parameters:one,two,andthreearesettothevalues1,2and3, respectively.Theparameters$userand$passhavespecial meaningtotheemailport.Youusetheseparametersto specifytheusernameandpasswordfortheemailport.You mustspecifythesetwoparametersifauthenticationis enabledontheemailport. Example:
one=1&two=2&three=3&$user=Administrator&$pass=manage
attachments.contenttype attachments.content OR attachments.filename
AStringsetto:text/xml Thebyte[]oraStringcontainingtheXMLdocument.
AStringspecifyingthefullyqualifiednameofthefile containingtheXMLdocument.
Receiving XML via E-mail

Ifyouremailportisconfiguredtoreturnresults,theresultsfromaserviceinvoked throughtheportareemailedbacktothesenderoftheoriginalmessage,inan attachmentfilecalledxml.out. Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresultsfromthe service(thatis,thecontentsofthepipeline)areXMLencodedandreturnedasan XMLdocument. Iftheservicehasanoutputtemplateassignedtoit,thattemplateisappliedtothe results. Important! Bydefault,theemailportdoesnotreturnanyresultsfromrequeststhatit receives.Ifyouwanttheporttoreturnresults,youmustexplicitlyconfigureittodo so.Forinformationaboutconfiguringtheemailporttoreturnresults,seethe webMethodsIntegrationServerAdministratorsGuide.
18
Using the Load and Query Services

20 20 21 36 61
What Are the Load and Query Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the loadXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the queryXMLNode Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Load and Query Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
2 Using the Load and Query Services
What Are the Load and Query Services?

ThewebMethodsIntegrationServerisequippedwithasetofloadandqueryservices thatallowyoutofetchHTMLorXMLdocumentsviaHTTPorHTTPSandselectively extractinformationfromthemforotherservices.Throughtheseservices,youcanconnect aservicetovirtuallyanydocumentontheInternet.(Ifyouwanttoretrievedocuments fromalocalfilesystem,seepub.file:getFileinthewebMethodsIntegrationServerBuiltIn ServicesReference.) FetchinganXMLdocumentfromtheInternetwithwebMethodsIntegrationServerisa twostepprocess. First,youusethepub.xml:loadXMLNodeservicetoretrievethedocumentthatcontains theinformationyouneed. Next,youextractthepiecesofinformationyouneedtouseandassignthemtoIS variables.Forthisstep,youcanusethepub.xml:queryXMLNodeservice(toselectspecific elementsfromthedocument)orthepub.xml:xmlNodeToDocumentservice(toconvertall elementsinthedocumenttovariables).
Basic Concepts
TosuccessfullyusewebMethodsIntegrationServersloadandqueryservices,youshould understandthefollowingtermsandconcepts.
What Is Parsing?
ParsingistheoperationthattheserverperformstoconvertanXMLdocument(astring) intoanXMLnodewhoseelementscanbeaddressedandextractedbyservices. webMethodsIntegrationServerautomaticallyparsesXMLdocumentsthatyoufetch withtheloadXMLNodeservice.
What Is a Node?
Anodeistheresultofaparsingoperation.Itisanelementbasedrepresentationofan XMLdocument.Thenodeexpressesadocumentinatreelikestructurethatallowsthe datawithinittobeefficientlyaddressedandlinkedintoservices.
What Is a Query?
WithrespecttoXMLnodes,aqueryisanexpression,writtenintheXMLQueryLanguage (XQL)orthewebMethodsQueryLanguage(WQL)thatyouusetoextract(filter) informationfromXMLnodes.
20
Using the loadXMLNode Service

Youusethepub.xml:loadXMLNodeservicetoretrieveanXMLorHTMLdocumentfromthe Internet.Thisservicedoesthefollowing: ItsubmitsaHTTPorHTTPSrequestforaspecifiedXMLorHTMLdocument. ANDTHEN Itparsesthereturneddocument. TheoutputfromloadXMLNodeisanXMLnodethatcanbeusedwithanyservicethattakes adocumentoranodeasinput. Note: Ifyouwanttofetchadocumentfromalocalfilesystem,donotuseloadXMLNode. Instead,usethepub.file:getFileservice.
Adding loadXMLNode to a Flow Service

Thefollowingproceduredescribesthestepsyouusetoinsertpub.xml:loadXMLNodeintoa flowservice. Important! Thefollowingprocedureexplainshowtomanuallyinsertandspecifythe loadXMLNodeservice.Ifyouareconstructingaloadandqueryservice,however,you maywanttousethewizardinstead.Thiswizardallowsyoutobuildaloadandquery sequencebypointingtoaURL.Forinformationaboutusingthewizardtocreatea loadandquerysequence,seeLoadandQueryShortcutsonpage 61. To insert loadXMLNode into a flow service 1 2 OpentheserviceinwhichyouwanttoinsertloadXMLNode. Click ontheeditortoolbar,andselectloadXMLNode.(IfloadXMLNodedoesnot appearonthemenu,clickBrowseandselectpub.xml:loadXMLNodefromthelistnextto Folder.) ClickthePipelinetabifitisnotalreadydisplayed. CompletethefollowingstepstospecifytheURLofthedocumentthatyouwantto retrieve. a b c InServiceIn,selecturl. Click onthetoolbar.
3 4
TypetheURL,startingwithhttp:orhttps:,andthenclickOK. Examples Thefollowingstringwouldretrievethespecifieddocumentviahttp:

http://www.rubicon.com/orders/orders.xml
21
Thefollowingstringwouldretrievethedocumentviahttps:
https://www.rubicon.com/orders/orders.xml
Usethe SetValuemodifiertoassignvaluestotheremaininginputvariablesas needed.FormoreinformationabouttheinputvariablesforloadXMLNode,seeInputs forloadXMLNodeonpage 22.
Input and Output Values for loadXMLNode

TheinputsforloadXMLNodespecifywhatdocumentyouwanttoretrieve,whatdata(if any)youwanttosubmitwiththerequest,andhowyouwantwebMethodsIntegration Servertoparsethedocumentitreceives. WhenyouuseloadXMLNodeinaflowservice,youusethe Set Valuemodifierinthe Pipelinetabtoassignvaluestothesevariables.IfyoucallloadXMLNodefromaprogram, yourprogrammustsetthesevariablesintheIDataobjectitpassestothe pub.xml:loadXMLNodeservice. Service inputs for loadXMLNode
Use the Set Value modifier to assign input values to loadXMLNode.
Inputs for loadXMLNode

ThefollowingdescribestheinputvaluesusedbytheloadXMLNodeservice.
The url variable

SetthisvariabletospecifytheURLofthedocumentyouwanttoretrieve. Example http://www.rubicon.com/orders/orders.html Thevalueyouspecifymustbeastringthatstartswiththeprotocolspecifierhttp: orhttps:
22
Youmayincludeaquerystring(forexample,acollectionofname=valuepairs)with thestringthatyouspecify.However,wesuggestthatyouusethedatavariableforthis typeofinformationinstead.Itisusuallyamorepracticalplaceforname=value data,becauseitallowsyoutolinkindividualvariablesinthequerystring.SeeThe datavariableonpage 25. To assign url in a flow service Dooneofthefollowing: Usethe OR Usethe Set ValuemodifierinthePipelinetabtospecifytheURLyouwanttouse. Linkmodifiertoassignapipelinevariabletourl.
The method variable

SetthisvaluetospecifytheHTTPmethod(GETorPOST)thatyouwantthetargetserver toexecuteontheresourcespecifiedinurl.Thisvaluedeterminesthewayinwhich loadXMLNodesubmitsdatavalues(ifany)totheresourceidentifiedinurl. Ifyousetmethodtoget,loadXMLNodeappendsthevaluesyouspecifyindatatothe valueinurl.(NotethatonlycertaindataelementsarevalidwhenyouusetheGET method). Ifyousetmethodtopost,loadXMLNodesendsthevaluesindatainthebodyofthe HTTPorHTTPSrequest. To assign method in a flow service Dooneofthefollowing: Usethe OR Usethe Set ValuemodifierinthePipelinetabtoselectthemethodyouwanttouse. Linkmodifiertoassignapipelinevariabletomethod.
Setting the method variable in a flow service
Select get or post from the list.
23
The auth variable

Youusethisvariabletospecifytheauthorizationandauthenticationcredentials(for example,usernameandpassword)thatyouwantloadXMLNodetosubmitwhenitrequests thespecifieddocument. Tosettheauthvariablecorrectly,youmustknow: WhethertheInternetresourceyouareaccessingisprotectedand,ifso,whattypeof authenticationisrequiredtoaccessit.Iftheresourceisnotprotected(thatis,itdoes notrequireausernameandpassword)youdonotneedtosetanyoftheelementsin auth. Theusernameandpasswordthatisrequiredbytheresourceyouarerequesting. Iftheresourceyouarerequestingisprotected,youmustspecifytheauthvariablewhen youuseloadXMLNode.EachelementinauthspecifiesapieceoftheAuthorizationfield thatloadXMLNodewillsubmittothetargetserver. Set this element... type user To specify... Theprotectionschemeusedtocontrolaccesstotherequested document.Ifyouareaccessingaprotectedresource,settoBasic. Ausernamethathasauthoritytoaccesstheresourcespecifiedin url. Thisvaluedefaultstothevalueofwatt.net.httpUserintheservers configurationfile(server.cnf). pass Thepasswordassociatedwiththeusernamespecifiedinuser.Ifthe userdoesnotrequireapassword,leavepassempty. Thisvaluedefaultstothevalueofwatt.net.httpPassintheservers configurationfile(server.cf). To assign auth in a flow service Dooneofthefollowing: Usethe Linkmodifiertoassignapipelinevariabletothetype,user,and/orpass elementsasneeded. OR Usethe Set ValuemodifierinthePipelinetabtohardcodethetype,user,and/orpass elementsasneeded.
24
The data variable

UsethedatavariabletospecifydatathatyouwantloadXMLNodetosubmittotheresource identifiedinurl. Important! Ifyouincludeyourdatawiththestringinurl,donotspecifyavalueindata. ThedatavariableisaDocumentthatcontainsseveralpredefinedelements.Eachelement allowsyoutospecifydatainadifferentway.(Notethatsomeelementsarevalidforonly oneHTTPmethod:GETorPOST.) Note: Ifyousubmitdatausingtheargsortableelement,loadXMLNodeautomaticallysets theHTTPContentTypeheadertoapplication/x-www-form-urlencoded.Ifyouwant tospecifyadifferentContentType,usethestringorbyteselementtosubmityour data,notargsortable. Use this element... args If you want to... Specifyname=valuepairsasstringelementsinaDocument. Whenyouspecifydatainthismanner,loadXMLNodeautomatically appendstheelementsfromargstourl(ifyouareusingtheGET method)orinsertstheminthebodyofthemessage(ifyouareusing thePOSTmethod). Tospecifydatainthismanner,createonestringelementforeach name=valuepairthatyouwanttosubmit,where: Thenameoftheelementdefinesthenameportionofthepair, and Thevalueoftheelementspecifiesthevalueportionofthepair. NotethatloadXMLNodewillautomaticallydothefollowing: URLencodevaluesyouspecify. Insertthe&characterbetweeneachname=valuepairthatit constructsfromtheargs(forPOSTandGET).Youdonothave toincludethischaracterinthevaluesyouspecify. Insertthe?characteratthebeginningofthequerystringit generatesfromargsfortheGETmethod.Youdonothaveto includethischaracterinthevaluesyouspecify. Important! Ifyouneedtospecifymultiplevaluesforasinglevariable (forexample,a=b&a=c&a=d),usethetableelement.
25
Use this element...
If you want to... Note: Whenyouusemorethanoneelementtosubmitdatawith loadXMLNode,argsisappendedfirst,tableisappendedsecond,and stringisappendedlast. ThefollowingproceduredescribeshowtousethePipelinetabto assigndatatoargsinaflowservice. To assign name=value pairs in args 1 2 3 4 5 6 SelecttheloadXMLNodestepintheeditor,andthenclickthe Pipelinetab. InService In,selectargs. Click onthetoolbarandselectString.
Typethenameportionofthefirstname=valuepair,andpress ENTER. Click tomakethatelementachildofargs.
Ifyouwanttoassignahardcodedvaluetothiselement,dothe following: a b Click onthetoolbartoopentheInput fordialogbox.
Typethevalueportionofthename=valuepair.Youdonot needtoURLencodethevalueifyouareusingtheGET methodtosubmitdatabecauseloadXMLNodewilldothisat runtime(forexample,itwillconvertGlobalSporting GoodstoGlobal+Sporting+Goods). ClickOK. tocreate
c 7
Toassignthevalueofapipelinevariableforargs,selectargsand theappropriatevariableinPipeline Inandthenclick alinkbetweenthem.
Repeatsteps 37foreachname=valuepairyouwantto submit.
26
Use this element... table
If you want to... Specifyyourdatainatwocolumntableofstrings.Whenyouspecify datainthismanner,loadXMLNodeautomaticallyappendstheelements fromtabletourl(ifyouareusingtheGETmethod)orinsertsthemin thebodyofthemessage(ifyouareusingthePOSTmethod). Thetablevariableissimilartotheargsvariable;however,table allowsyoutosubmitvaluesthatarenotpartofaname=value construction.Forexample,ifyourInternetresourceexpectsasetof unnamedvaluessuchas http://www.rubicon.com/orders?GSG&40019&openinsteadof name=valuepairs,youmustspecifythosevaluesintable.Thisis becauseargsonlyproducesname=valuepairs. Tosubmitdataviathetableelement,createarowforeachvariable thatyouwantloadXMLNodetosubmit,where: Thecontentsofcolumn0specifythenameportionofthepair(if itisanunnamedvariable,leavethiscellblank),and Thecontentsofcolumn1specifythevalueportionofthepair. NotethatloadXMLNodewillautomaticallydothefollowing: URLencodevaluesyouspecify. Insertthe&characterbetweeneachname=valuepairthatit constructsfromtable(forbothPOSTandGET).Youdonothave toincludethischaracterinthevaluesyouspecify. Insertthe?characteratthebeginningofthequerystringit generatesfromtablefortheGETmethod.Youdonothaveto includethischaracterinthevaluesyouspecify. Important! Whenyouuseargsandtabletosubmitdatawith loadXMLNode,theserviceappendsargsfirstandtablesecond.The serviceappendsstringlast.
27
Use this element...
If you want to... ThefollowingproceduredescribeshowtousethePipelinetabto assigndatatotableinaflowservice. To assign name=value pairs in table 1 2 3 SelecttheloadXMLNodestepintheeditor,andthenclickthe Pipelinetab. InService In,selecttable. Ifyouwanttoassignasetofhardcodedvaluestotable,do thefollowing: a b c d Click Click Click onthetoolbartoopentheInput fordialogbox. twicetocreatetwocolumns(0and1). tocreateanemptyrow.
Selectcell0andtypethenameofthename=valuepair thatyouwanttosubmittotheInternetresourceinurl. (Ifyouaresendinganunnamedvariable,leavethiscell empty.) Selectcell1andtypethevalueofthename=valuepair thatyouwanttosubmittotheInternetresourceinurl. (Ifspecifyinganunnamedvariable,typethevariables value.) Repeatsteps ceforeachvariablethatyouwantto specify. ClickOK.
f g 4
Toassignthevalueofapipelinevariablefortable,select tableandtheappropriatevariableinPipeline Inandthen click tocreatealinkbetweenthem.(Notethatthe variableyoulinktotablemustbeatwocolumntableof strings.)
28
Use this element... string
If you want to... Specifyyourdataasasinglestringoftext.Whenyouspecifydatain thismanner,loadXMLNodeautomaticallyappendsthespecifiedstring tourl(ifyouareusingtheGETmethod)orinsertsitintothebodyof themessage(ifyouareusingthePOSTmethod). Keepthefollowingpointsinmindwhenyouusestringtosubmit datawithloadXMLNode. Ifyouarespecifyingasetofname=valuepairs,stringmuststart withthefirstnameintheset. ExampleAccountNum=GSG-970414A Youdonotneedtoincludethe?symbolatthebeginningofthe stringbecauseloadXMLNodewillautomaticallyinsertthissymbol whenitappendsstringtothecontentsofurl. IfyouareusingtheGETmethod,besuretoformatstringasa validquerystring.Thatis,separatevariableswiththe& character(asshowninExample1)andURLencodetheirdata values(asshowninExample2). Example 1AccountNum=GSG-970414A&postalCode=22031 Example 2 CompanyName=Global+Sporting+Goods IfyouareusingthePOSTmethod,formatthestringexactlyas youwantittoappearinthebodyofthemessage. Important! Whenyouusemorethanoneelementtosubmitdatawith loadXMLNode,argsisappendedfirst,tableisappendedsecond,and stringisappendedlast.
bytes
Specifyyourdataasanarrayofbytesthatyouwantpostedtothe resourceinurl.Youcanusethisvariablewhenyouneedtosendnon textualdatatoanInternetresource. Toassignavaluetobytesinaflowservice,usethePipelinetabtolink thevariablecontainingyourbytearraytobytes. Important! loadXMLNodeonlyusesthebyteswhenmethodissettoPOST. Note: Whenyouusebytesandanotherelement(args,table,orstring)to submitdatawithloadXMLNode,theserviceappendsthedatafromthe args,table,orstringelementtourl.Theserviceappendsargstourl first,tablesecond,andstringlast.Theserviceencodesthedatafrom thebyteselementinthebodyofthepost.
29
The headers variable

YouusethisvariableifyouwanttospecifythevalueofaheaderfieldintheHTTP requestthatloadXMLNodesubmitstothetargetserver. Bydefault,loadXMLNodeissuesastandardsetofheaderfields.(Thevaluesofsomeofthese fieldsareconfiguredwhenyourwebMethodsIntegrationServerisinstalled.Consult yourserveradministratorifyouwanttoknowyourserversdefaultsettings.)Tousea headervalueotherthanthedefault,youcanspecifyitintheheadersvariable. Important! Inmostcases,thedefaultheadersthatloadXMLNodeusesareadequate.You shouldnotaddorchangerequestheaderfieldsunlessyouarethoroughlyfamiliar withtheHTTPprotocol. IfyouwanttoassignspecificvaluestoheaderfieldsusedbyloadXMLNode,keepthe followingpointsinmind: Whenyouspecifythevalueofaheaderfield,youoverridewhateverdefaultvalue webMethodsIntegrationServerisconfiguredtouseforHTTPrequests.Forexample, ifyousettheUserAgentheaderfieldtoB2B/3.0,theserverusesthatvalueinsteadof thedefaultvaluespecifiedbythewatt.net.userAgentparameter. TheloadXMLNodeserviceautomaticallydeterminesthevalueoftheContentLength headerfield.YoucannotspecifyavalueforContentLength. Beawarethatwhenyousubmitdatausingtheargsortableelements,loadXMLNode automaticallysetstheContentTypeheaderfieldtoapplication/x-www-formurlencoded.Youcannotoverridethissettingusingtheheadersvariable.Ifyouwant toexplicitlyspecifyacontenttypeinheaders,makesuretousethestringorbytes elementtosubmityourdata,notargsortable. Certainheaderfieldsareautomaticallyderivedfromotherinputparametersassigned toloadXMLNode.Forexample,theAuthorizationheaderfieldisautomaticallyderived fromyourauthparametersetting.ExceptfortheContentLengthheaderfieldandthe ContentTypeheaderfield(which,asdescribedabove,youcannotoverridewhen submittingdataviaargsortable),avaluethatyouspecifyinheadersoverridesthe valuethatloadXMLNodemightotherwisederivefromotherparametersettings. TheloadXMLNodeservicedoesnotvalidatedatathatyouspecifyinheaders.Itsimply passesitontothetargetserverintherequestheader.Makesureyouspecifyheaderfield namesandtheirvaluescorrectly.Foracompletelistofvalidrequestheaderfields,see http://www.w3.orgforthelatestHTTPspecificationpublishedbytheW3C. Tospecifyrequestheadersinheaders,createastringelementforeachheaderthatyou wanttospecify,where: Thenameoftheelementdefinesthenameheaderfield(forexample,UserAgent,If ModifiedSince,Mail_Address),and Thevalueoftheelementspecifiesthevalueyouwantassignedtothatfield.
30
ThefollowingproceduredescribeshowtousethePipelinetabtoassignvaluestoheaders inaflowservice. To specify header fields in headers 1 2 3 4 SelecttheloadXMLNodestepintheeditor,andthenclickthePipelinetab. InService In,selectheaders. Click onthetoolbarandselectString.
Typethenameoftheheaderfieldthatyouwanttospecify.(Youdonotneedtotypea colonafterthefieldnamebecauseloadXMLNodewillautomaticallyinsertthecolon whenitinsertsthisfieldintotherequestheader.) Click tomaketheelementachildofheaders.
5 6
Ifyouwanttohardcodethevalueofthiselement,dothefollowing: a b c Click onthetoolbartoopentheInput fordialogbox.
TypethevaluethatyouwantloadXMLNodetoassigntotheheadersfield. ClickOK. tocreatealinkbetweenthem.
7 8
Toassignthevalueofapipelinevariableforheaders,selectheadersandtheappropriate variableinPipeline Inandthenclick Repeatsteps 37foreachheaderfieldthatyouwanttosubmit.
The encoding variable

Youusethisvariabletospecifythecharacterset(forexample,ISO88591)inwhichthe returneddocumentisencoded.Theparserusesthisvaluetoproperlyreadthetextinthe document. YoumaysetencodingtoautoDetectortothenameofaspecific,IANAregistered characterset.WhenyousetencodingtoautoDetect,loadXMLNodesetsthecharacterset basedonwhetherthedocumentcontainsXMLorHTML.Seethetablebelowfordefaults. Toexplicitlyspecifyacharacterset,specifythenameofthatcharactersetinencoding. ValidcharactersetnamesarelistedintheInternetAssignedNumbersAuthority(IANA) charactersetregistry. Ifyoudonotspecifyencoding,theparserassumesthefollowingdefaultsdependingon thetypeofdocumentitreceives: If the document type is... HTML XML encoding defaults to... ISO88591 UTF8
31
ThefollowingproceduredescribeshowtousethePipelinetabtoassignvaluesto encodinginaflowservice. To set the encoding value 1 2 3 SelecttheloadXMLNodestepintheeditor,andthenclickthePipelinetab. InService In,selectencoding. Ifyouwanttohardcodethevalueofthiselement,dothefollowing: a b Click onthetoolbartoopentheInput fordialogbox.
Typeoneofthefollowingintheencodingfield: Type... autoDetect If you want the parser to... Decodethedocumentbasedonthedocumenttype. AssumesISO88591forHTMLdocumentsandUTF 8forXMLdocuments. Decodethedocumentbasedonaspecifiedcharacter set.
The name of a registered IANA character set. c 4 ClickOK.
Toassignthevalueofapipelinevariableforencoding,selectencodingandthe appropriatevariableinPipeline Inandthenclick tocreatealinkbetweenthem.
The expandDTD variable

YouusethisvariabletospecifywhetheryouwanttheloadXMLNodeservicetoexpand instancesofnamedparameterentitiesinthereturneddocumentsDTD.Ifyouset expandDTDtotrue,loadXMLNodewillprocessparameterentityreferences,expanding themtotheirfulldefinition.IfyousetexpandDTDtofalse,loadXMLNodeignores parameterentityreferenceswhenitvalidatesthereturneddocument. Youmaywantorneedtousethisvariableincaseswhenyouhaveasyntacticallycorrect documentthatcausesaparseerrorbecauseitviolatesadefinitioninanexternal parameterentityreference.BysettingexpandDTDtofalse,youcanbypasstheexternal definitionsothatloadXMLNodecanparsethedocumentsuccessfully.
32
IfyoudonotexplicitlysetexpandDTD,loadXMLNodesetsittofalse. To set expandDTD in a flow service Dooneofthefollowing: Usethe Set ValuemodifierinthePipelinetabandselectthevalueofexpandDTD fromthelist. OR Usethe LinkmodifiertoassignapipelinevariabletoexpandDTD.Thepipeline variablemustsetexpandDTDtoavalueoftrueorfalse.(Thisvalueiscasesensitive.)
The isXML variable

YouusethisvariabletospecifywhetherthedocumentyouwanttofetchcontainsHTML orXML.Theserverrequiresthisvalueinordertoparsethecontentsofthedocument correctly. YoumaysetisXMLtoanyofthefollowingvalues: Value
autoDetect
Description Parsesthedocumentbasedonits<!DOCTYPE HTML >or<?xml version=?>tag.Ifitcannotdeterminewhattypeofdocumentithas,it parsesitasanHTMLdocument. ParsesthereturneddocumentasHTML. ParsesthereturneddocumentasXML.
false true
IfyouknowwhattypeofdocumentloadXMLNodewillreceive,wesuggestthatyou explicitlysetisXMLinsteadofusingautoDetect.Itwillcutprocessingtime,becausethe serverwillnothavetoexaminethedocumenttodetermineitstype.Thedefaultvalueis autoDetect. To set isXML in a flow service Dooneofthefollowing: Usethe list. OR Usethe LinkmodifiertoassignapipelinevariabletoisXML.Thepipelinevariable mustsetisXMLtoavalueofautoDetect,true,orfalse.(Thisvalueiscasesensitive.) Set ValuemodifierinthePipelinetabtoselectthevalueofisXMLfromthe
33
The loadAs variable

YouusethisvariabletospecifythewayinwhichloadXMLNodepassestheparsed documenttosubsequentservicesthatuseitasinput. YoumaysetloadAstothefollowingvalues: Value
bytes
Description Passestheparseddocumentasabytearray.Youusethissettingwhenthe outputfromloadXMLNodewillbeusedasinputtoaservicethatoperateson wholedocuments(forexample,pub.xml:queryXMLNodeand pub.xml:xmlNodeToDocument). Passestheparseddocumentasaninputstream.Youusethissettingwhen theoutputfromloadXMLNodewillbeusedasinputtoaservicethatcan incrementallyprocessadocument(forexample,pub.xml:getNodeIterator).
stream
IfyoudonotexplicitlysetloadAs,loadXMLNodesetsittobytes. To set loadAs in a flow service Dooneofthefollowing: Usethe list. OR Usethe LinkmodifiertoassignapipelinevariabletoloadAs.Thepipelinevariable mustsetloadAstoavalueofbytesorstream.(Thisvalueiscasesensitive.) Set ValuemodifierinthePipelinetabtoselectthevalueofloadAsfromthe
The failOnHTTPError variable

Youusethisvariabletospecifywhethertheservicefails(throwsanexception)ifit receivesanHTTPerrorasaresponse.Forexample,theservermightreturnanHTTP404 NotFounderrorfortherequestedURL.YoumaysetfailOnHTTPErrortooneofthe followingvalues: Value
false
Description TheservicedoesnotfailbasedontheHTTPstatuscodereturnedbythe remoteserver.Thisisthedefaultvalue. TheservicefailsiftheremoteserverreturnsanHTTPerror.Theexception messagecontainstheHTTPerrorcode,whichisdeterminedbytheW3C HTTPspecification.
true
34
To set failOnHTTPError in a flow service Dooneofthefollowing: Usethe Set ValuemodifierinthePipelinetabtoselectthevalueoffailOnHTTPError fromthelist. OR Usethe LinkmodifiertoassignapipelinevariabletofailOnHTTPError.The pipelinevariablemustsetfailOnHTTPErrortoavalueoftrueorfalse.(Thisvalueis casesensitive.)
Output Values from loadXMLNode

IfloadXMLNodeexecutessuccessfully,itproducesasingleoutput,anode,whichisanXML nodecontainingtheparsedHTMLorXMLdocument.Youusenodeasinputtoother servicessuchaspub.xml:queryXMLNode(toextractspecificelementsfromthedocument)and pub.xml:xmlNodeToDocument(toextractallofthedocumentselements). IfloadXMLNodeencountersanHTTPerrorduringexecution,theflowstepfailsandan exceptionisthrowniffailOnHTTPErrorissettotrue.Seethesectionthatfollows.
Error Handling With loadXMLNode

IfloadXMLNodefails,itreturnsanexception.IfloadXMLNodefailsbecauseofanHTTP errorandfailOnHTTPErrorwassettotrue,thenitreturnsanexceptionwiththeHTTP errorcode. CommonreasonsforloadXMLNodetofailinclude: urldoesnotbeginwithhttp:orhttps:. isXMListrue,butthedocumentcontainspoorlyformedHTML. Youhaveattemptedtoaccessaprotecteddocumentwithoutauthorization(thatis, missingorincorrectuserauth/userand/orauth/passsettings). loadXMLNodereceivesasyntacticallyincorrectdocumentthatcannotbeparsed. AnOutofMemoryerroroccurs. AnHTTPerror(forexample,theservercannotlocatetherequesteddocument) occurs. Anetworktimeoutoccurs. methodisnotGETorPOST. AnHTTPerror,suchas404filenotfoundoccurs.
35
Using the queryXMLNode Service

Youusethepub.xml:queryXMLNodeservicetoselectivelyextractinformationfromaparsed HTMLorXMLdocumentandassignthatinformationtovariablesthatcanbelinkedto otherservices. WhenyouusequeryXMLNode,youextractinformationusingeithertheXMLQuery Language(XQL)orthewebMethodsQueryLanguage(WQL).Bothlanguagesallowyou toaddressandselectinformationfromanodebasedoncriteriathatyouspecifyina querystatement.
Passing a Node to queryXMLNode

ThequeryXMLNodeservicetakesanodeasinput.WhenyouinvokequeryXMLNodeinaflow service,youmusthaveanodevariable(containingparsedXMLorHTML)alreadyinthe pipelineforqueryXMLNodetorunagainst. ThereareseveralwaysinwhichyoucanproduceanodeforqueryXMLNodetorunagainst. If you want your service to... FetchanXMLorHTML documentfroma specifiedURL. Queryastringofraw HTMLorXMLthatis storedinapipeline variable. QueryanXMLdocument thatissubmitteddirectly towebMethods IntegrationServer. Create a flow service that... 1 2 1 2 1 2 Invokespub.xml:loadXMLNode(togetthedocument fromtheWebandtransformittoanode),andthen Invokespub.xml:queryXMLNode. Invokespub.xml:xmlStringToXMLNode(totransformthe contentsofthestringtoanode),andthen Invokespub.xml:queryXMLNode. Takesanodeasinput,andthen Invokespub.xml:queryXMLNodeasthefirstservicein theflow. FordetailsonpostingXMLdirectlytoaservice,see SubmittingandReceivingXMLviaHTTPon page 13. ThemeansthatyouusetoobtainanHTMLorXMLdocument,convertittoanode,and passittothequeryXMLNodeserviceisadesigndecisionthatyoumustmakebeforeyou beginbuildingyourflow.
36
Addressing Information in a Node

WhenwebMethodsIntegrationServerparsesanHTMLorXMLdocument,ittransforms thedocumentintoatreelikestructurecontainingthedocumentsHTMLorXML elements.Onceadocumentisparsed,youcanaddressindividualelementswithinit usinganXQLorWQLquery. Forexample,inanHTMLdocument,youcouldusethefollowingquerytoextractthe contentsofthefirstparagraphinthedocument:
doc.p[0].text
InanXMLdocument,youmightuseanXQLquerythatlookslikethistoextractthe phonenumberfromanelementcalledsupplierInfoinaSalesOrderdocument:
/SalesOrder[0]/supplierInfo[0]/phoneNum[0]/text()
ThequeryXMLNodeserviceallowsyoutouseeitherlanguagetodefineaquery.Italso allowsyoutomakethischoiceonaquerybyquerybasis.Thatis,youcanextractsome informationfromthedocumentusingXQLandotherinformationwithWQL. Thelanguagethatyouuseislargelydeterminedbypersonalchoiceandtheneedsofyour application.Eachlanguagehasafewspecificfeaturesthattheotherdoesnot.Whenyou buildyourservice,youcantestyourqueriesusingeitherlanguagetodecidewhich providesthebetterresults. ForadescriptionofWQL,seeAppendix A,webMethodsQueryLanguage. ForadescriptionofXQL,seeTheXMLQueryLanguage(XQL),at http://www.w3.org/TandS/QL/QL98/pp/xql.html.
Working with a Sample Document

Tohelpyoubuildqueriesfasterandmoreaccurately,webMethodsDeveloperletsyou generatequeriesbypointingtoanelementinasampledocument.Thesampledocument thatyouuseshouldeitherbetheactualdocumentyourservicewillexecuteagainstatrun timeorarepresentativeexampleofthatdocument. Note: Althoughyoucandefinequerieswithoutloadingasampledocument,having oneallowsyoutocreateyourqueriesfasterandmoreaccurately. ToloadasampledocumentintoDeveloper,youexecuteyourflowintracemode (TestTrace).Whenyoudothis,DeveloperdisplaystheparseddocumentontheVariables tab.(TheVariablestabonlyappearswhenaqueryXMLNodeserviceisselectedintheeditor.)
37
The XML Node View tab displays the elements of a document
After you run queryXMLNode in Trace mode, the parsed document appears on the XML Node View tab.
TheVariablestabcontainstwoadditionaltabs:theXML Node ViewtabandtheSample View tab.
The XML Node View Tab

TheXML Node Viewtabshowsthenodes(addressablecomponents)thatarecontainedina document.Itallowsyoutobrowsethecontentsofadocumentandgeneratequeriesby pointingtothenodethatyouwanttoextract. Developerusesthefollowingsymbolstodenotedifferenttypesofnodesinadocument: Symbol Description AnHTMLorXMLelement(e.g.,<poNum></poNum>).Ifanelement containsadditionalnodes,the symbolappearsnexttoit.Clickthis symboltoviewadditionalnodeswithinanelement. Anelementattribute(forexample,name=Intro). Acomment.
38
The Sample View Tab

TheSample Viewtabdisplaystheresultofaquery.Whenyoucreateaquery,Developer dynamicallyexecutesthatqueryagainstthesampledocumentanddisplaystheresults ontheSample Viewtab. The Sample View tab displays the results of the selected query
When you create a query...
...you can view the results on the Sample View tab.
Adding queryXMLNode to a Flow Service

Thefollowingproceduredescribesthestepsthatyouusetoinsert pub.xml:queryXMLNode intoaflowservice.Thisprocedureassumesthatyouhaveaccesstoasampledocument thatyoucanloadanddisplayinDeveloper. Important! Thefollowingprocedureexplainshowtomanuallyinsertandspecifythe queryXMLNodeservice.Ifyouarebuildingaloadandquerysequence,youmaywant tousethewizardtobuildyourflowinstead.Itallowsyoutoquicklycreatealoadand queryservicefromaURLthatyouspecify.Forinformationaboutusingthewizardto createaloadandqueryservice,seeLoadandQueryShortcutsonpage 61.
39
To insert queryXMLNode into a flow service 1 2 OpentheflowinwhichyouwanttoinsertthequeryXMLNodeservice. Intheeditor,selectthepointwhereyouwanttoinvokequeryXMLNode,click in theeditortoolbar,andselectqueryXMLNodefromthelist.(IfqueryXMLNodedoesnot appearonthelist,clickBrowseandselectpub.xml:queryXMLNodefromthelistnextto Folder.) DooneofthefollowingtoloadyoursampleXMLorHTMLdocumentinto Developer:
IfyourflowpassesaparsedXMLorHTMLdocumenttoqueryXMLNodeviaa loadXMLNodeorxmlStringToXMLNodestep,selecttheTracecommandontheTestmenu toexecutetheflow.(MakesurethatthevariablesintheloadXMLNodeor xmlStringToXMLNodeservicearealreadycorrectlyspecifiedsothatitwillgenerate nodesuccessfully.) IfyourflowexpectstheservertopassaparsedXMLdocumenttoit,selectthe Send XML FilecommandfromtheTestmenu,andthendothefollowing: 1 2 IntheSelect Test Modedialogbox,selectTraceandclickOK. IntheSelect Filedialogbox,selectyoursampleXMLfileandclickOpen.
4 5 6
Whenthetracefinishesexecuting,selectthequeryXMLNodestepintheeditor,andthen selectXML Node ViewontheVariablestab. Createaqueryforeachpieceofinformationthatyouwanttoextractfromthe document.SeeSpecifyingaQueryonpage 41fordetailedprocedures. Ifyouuseanamespaceprefixtoqualifyelementnamesinyourquery(forexample, /GSG:supplierInfo/name/text()),ANDyouwanttolinkthatprefixtoaspecific namespaceinthedocument,usethefollowingproceduretoassigntheprefixtothe documentsnamespace.(IfyoudonotusenamespaceprefixesinyourqueriesORthe prefixesyouusematchtheonesusedinthedocument,youcanskipthisstep.) a b c ClickthePipelinetab. SelectthensDeclsvariableinService Inandclick fordialogbox. Click andspecifythefollowing: Specify... Theprefixyouusetorepresentanamespaceinyourqueries. Thenamespacerepresentedbythisprefix.(Namespacesare namedusingURLnotation.) onthetoolbartoopentheInput
In this field... Name Value
40
d e
ClickOK. Repeatsteps canddforeachnamespaceprefixthatyouneedtodefine.Whenyou arefinished,clickOKtoclosetheInput fordialogbox.
Specifying a Query
YouusetheVariablestabtodefinethequeriesthatqueryXMLNodewillexecutetopopulatea setofvariables.Theleftsideofthetabdisplaysthelistofvariablesthatyouwant queryXMLNodetopopulate.Therightsideofthetabcontainsthecontrolsyouusetobuilda querythatwillpopulateavariable. Toexamineand/oreditthequeryforaparticularvariable,youselectthevariablefrom thelistontheleftsideandviewand/oradjustthesettings(Query,Type,Allow Null,andso forth)ontheright. The Variables tab defines the variables that queryXMLNode will produce
This list displays the set of variables that queryXMLNode will produce.
41
Therearetwowaysyoucandefineavariable(andthequerythatwillpopulateit)for queryXMLNode: YoucanmanuallytypethequeryintotheVariablestab. OR Youcancreatethequerybypointingtothenodeyouwanttoextract.
Specifying a Query Manually

Ifyouarefamiliarwiththecontentsandstructureofthedocumentyouwanttoquery, youcanmanuallybuildaquerytoextractinformationfromit.Whenyoucreateaquery inthisway,youdonotneedtoloadasampledocumentintoDeveloper(however,you mayeventuallywanttoloadonetotestyourqueriesandverifythattheyworkcorrectly). Thefollowingproceduredescribeshowtomanuallycreateaninputvariableforthe queryXMLNodeserviceandassignaquerytoit. To manually create a variable for a queryXMLNode service 1 2 3 4 IfthetoolbarontheVariablestabisnotactive,clickanywhereinthevariableslistbox (thewhiteareaontheleftsideofthetab)toactivateit. Click onthetoolbartocreateanewvariableinthelist.
TypeanameforthevariableandpressENTER. Setthefollowingoptions: Set this option... WQL/XQL To specify... Thelanguageinwhichyouwillwritethequery. Set... WQL XQL Allow Nulls To... UsethewebMethodsQueryLanguage. UsetheXMLQueryLanguage.
Whetheranullornonnullresultshouldcausetheservicetofail atruntime. Set... Allow Null Fail if Null Fail if Not Null If queryXMLNode should Acceptbothnullandnonnullresults. Issueanexceptionifthequeryproducesanull result. Issueanexceptionifthequeryproduces anythingbutanullresult.
42
Set this option... Type 5
To specify... Thedatatypeofthevariableinwhichyouwantthequeryresult stored
IntheQueryfield,typeyourqueryandthenpressENTER. Important! WhenqueryinganXMLdocument,makesuretotypenodenamesexactly astheyarespecifiedinthedocument.ForXML,nodenamesarecasesensitive! (HTMLnodenamesarenot.) DeveloperautomaticallyexecutesthequerywhenyoupressENTER.Ifyouhavea sampledocumentloaded,youcanclicktheSample Viewtabtodisplaytheresult.
Specifying a Query by Pointing to a Node

Tocreatequeriesquicklyandaccurately,youcanselectanodeintheXML Node Viewtab andhaveDeveloperautomaticallybuildaquerythatselectsthetextforthatelement. AfterDeveloperbuildsthequery,youcanuseitasisoreditittosuityourneeds.
\
Important! Tousethefollowingprocedure,youmustloadthesourcedocumentinthe XML Node Viewtab.Ifyouhavenotalreadydonethis,runtheTestTracecommand(if queryXMLNodereceivesthenodefromaloadXMLNodeorxmlStringToXMLNodeservice)or TestSend XML File(ifqueryXMLNodereceivesinputdirectlyfromtheserver)beforeyou begin. Important! ThefollowingprocedureproducesaqueryinDevelopersdefaultquery language.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
1 2 3
OntheXML Node Viewtab,selectthenodeforwhichyouwanttogenerateaquery. RightclickandselectCreate New Variable from Node. Typeanameforthevariablethatwillholdtheresultsofthequery,andpressENTER.
43
Setthefollowingoptions: Set this option Allow Null To specify... WhatqueryXMLNodeshoulddoifthequeryproducesanullresult atruntime. Set Allow Null Fail if Null Fail if Not Null Type If queryXMLNode should Acceptbothnullandnonnullresults. Issueanexceptionifthequeryproducesanull result. Issueanexceptionifthequeryproduces anythingbutanullresult.
Thedatatypeofthevariableinwhichyouwantthequeryresult stored.
Ifnecessary,editthequeryintheQueryfield.PressENTERwhenyoufinisheditingto reexecutethequery.Toviewtheresults,clicktheSample Viewtab.Foradditional informationaboutcreatingqueries,seeUsingWQLandXQLbelow.
Using WQL and XQL

WQL(webMethodsQueryLanguage)isalanguagethatisusedtoretrieveinformation fromanHTMLorXMLdocument.WQLusesanobjectreferenceandanobjectpropertyin ordertoextractdocumentelementsfromanHTMLorXMLdocument.Initssimplestform, thesyntaxisObjectreference.Objectproperty.Forexample,order[].text means:Select thetextofallorderelementsinaparticularcontext(forexample,withinanXMLfile). XQL(XMLQueryLanguage)isalanguagethatisusedtoretrieveinformationfroman XMLdocument.XQLusessimpledirectorynotation.Forexample,order/lineItemmeans: SelectalllineItemelementsinallorderelementsinaparticularcontext(forexample, withinanXMLfile).YoucanalsouseBooleanlogictofilteroutelements,selectallnodesof aparticularvalue,selectallnodeswithnodesinparticularranges,andsoforth.
Using WQL in a Query

AWQLqueryconsistsofoneormoreindexedelementarraysandanobjectproperty.For example,allofadocumentssnowboardproductelementsmaybecollectedintoanarray calledsnowboard[],itsproductnamesmaybecollectedintoanarraycalledname[],its productpricesmaybecollectedintoanarraycalledprice[],andsoforth.
44
Partial XML document

<?xml version="1.0"?> <bitterrootboards> <snowboard> <name>Globe</name> <type>Freeride/Freestyle</type> <sku>A</sku> <length>149</length> <width>28.5</width> <price>279</price> <availability>true</availability> </snowboard> <snowboard> <name>Pro Series</name> <type>Freeride/Powder/Extreme</type> <sku>B</sku> <length>156</length> <width>28.9</width> <price>399</price> <availability>false</availability> </snowboard> </bitterrootboards>
Thearraysareindexednumerically,beginningwith0.Toextractaparticularelement, youspecifyitsaddresswithinthearrayofwhichitisamember.Forexample,the followingistheWQLqueryforthefirstsnowboardelementinthepreviousexample:

doc.snowboard[0].text
Anobjectpropertyspecifiesthetypeofinformationthatyouwanttoextractfromthat element.IntheWQLexampleabove,the.textsuffixspecifiesthatyouwanttoextract thetextcontainedwithindoc.snowboard[0].Thissuffixistheobjectproperty.This propertycaneitherbeoneofwebMethodspredefinedpropertiesoroneoftheelements attributes(forexample,WIDTH,ALIGN,HREF). webMethods Predefined Properties WQLprovidesasetofpredefinedpropertiesthatyoucanusetoextractspecifickindsof informationfromanelement.Forexample,togetthetextcontainedinthe<name> elementshownbelow:
<name>Globe</name>
Youusethe.textpropertyasfollows:
doc.name[0].text
ThefollowingtabledescribesthesetofpredefinedpropertiesinthewebMethodsQuery Language.Notethateachpropertyhastwonames.Thisprovidesanalternativename youcanuseincaseswhereanelementhasanattributewiththesamenameastheWQL
45
property(theattributenametakesprecedenceoveraWQLpropertynamewhenthetwo namesarethesame). Use this property

.text .txt
To get Thetextcontainedwithinthespecifiedelement.Ifthespecified elementcontainschildelements,thecontentsofallofthose elementsareextractedtoo. Example doc.name[0].text Result "Globe"
.value .val
Thevaluecontainedwithinthespecifiedelement.Ifthespecified elementcontainschildelements,thevaluesforallofthose elementsareextractedtoo. Example doc.name[0].value Result "Globe"
.source .src
TheXMLorHTMLsourcecodeforthespecifiedelement. Example doc.name[0].source Result <name>Globe</name> TheXMLorHTMLsourcecodegeneratedfromtheparsetreeof thedocument.Thedifferencebetween.sourceand.csourcecanbe thatsometagsandattributesofthesourcefilesaremodifiedto matchthespecification. Example doc.name[0].csource Result<name>Globe</name>
.csource .csrc
.index .idx
Theindexofthespecifiedelement. Example doc.name[0].index Result 0 Thecompleteobjectreferenceforthespecifiedobject. Example doc.name[0].reference Result Doc.name[0] TheURLofthedocument. Example doc.url Result http://www.AcmeCorp.com/documentArchive
.reference .ref
.url
46
Element Attributes InadditiontothepredefinedpropertiesprovidedbythewebMethodsQueryLanguage, youcanalsospecifyanattributenameasaproperty.Whenyouspecifyanattributename asaproperty,thequeryreturnsthevalueofthatattribute.Forexample,inthefollowing XMLelement:

<part name="Widget" sku="123456" quantityonhand="5000"> </part>
Youwouldusethefollowingquery:
doc.part[0].sku
ToextractthefollowingfromtheSKUattribute:
"123456"
Specifying Multiple Elements Toextractasingleitemfromadocument,specifyaquerythatextractsasinglememberof thatarrayasshowninthefollowingexamples: This reference

doc.snowboard[0].text doc.snowboard[1].text doc.snowboard[5].text
Returns data from Thefirstsnowboardelementinthedocument. Thesecondsnowboardelementinthedocument. Thesixthsnowboardelementinthedocument.
Toextractmultiplemembersfromanobjectarray,youcanspecifythoseobjectsusing specialindexnotationasshowninthefollowingexamples. This reference

doc.snowboard[ ].text doc.snowboard[110].text doc.snowboard[1-end] doc.snowboard[1,3,7] doc.snowboard[1-3,5-7] doc.snowboard[2+2]
Returns data from Allsnowboardelementsinthedocument. Snowboardelements1through10inthedocument. Snowboardelements1totheendofthedocument. Snowboardelements1,3,and7. Snowboardelements1,2,3,and5,6,7. Snowboardelements2,4,6,8
Foracompletedescriptionoftheindexvalueoptions,seeAppendix A,webMethods QueryLanguage.
47
Nested Element References Youcanspecifyanelementrelativetoanyoftheelementsitiscontainedwithin(thatis, relativetoitsparentcontainers).Forexample,thesecondproductnameelement (underscoredbelow)inthefollowingXMLfragment:

<snowboard> <name>Vert</name> <type>Freestyle/Pipe/Park</type> <sku>D</sku> <length>154</length> <width>25</width> <price>479</price> <availability>true</availability> </snowboard> <snowboard> <name>Trauma</name> <type>Freestyle/Pipe/Park</type> <sku>E</sku> <length>153</length> <width>29.4</width> <price>367</price> <availability>true</availability> </snowboard>
Canbereferencedineitherofthefollowingways:
doc.name[1].text doc.snowboard[1].name[0].text
Theindexvaluevaries,dependingonwhichparentelementsyouincludeinthe reference.ThefirstcontainerinaWQLqueryisalwaysdoc,whichreferencesanode. The Scope of a WQL Query Nestedobjectreferencesalsodefinethescopeofaquery.Eachofthefollowingexamples referencesanelementcalledname[0],butbynestingelementsinthequery,youconstrain thescopeofthatquery. For this query
doc.name[0].text doc.snowboard[0].name[0].text doc.bitterrootboards[2]. snowboard[0].name[0].text
The scope is Theentiredocument. Thefirstsnowboardelementinthedocument. Thefirstsnowboardelementwithinthethird bitterrootboardselementinthedocument.
48
Referencing Data in Tables ToretrievetheentirecontentsofatablewithinanHTMLdocument,specifythattables indexvalue,anduse[]fortherowsandcolumnsinthattable.

doc.table[0].tr[].td[].text
Besidestablereferences,otherqueriescancreateatableasaresult.Forexample,the followingquerygetsallboldtextfromalllistitemsinanHTMLdocument:
doc.ul[0].li[].b[].text
Itsresultmaybeoneormorebolditemsfromeachlistitem.Toholdthistypeofoutput, thevariablemustalsobeaStringTable. Note: Referencesthatcombinemorethantwoarraysarecollapsedintotwo dimensionaltables. Using Search Strings as Index Values Youcanusepatternmatchingstringsinsteadofindexnumberstoselectmembersofan elementarray.Thistypeofqueryreturnsdatafromthoseelementswhosetextproperty matchesthespecifiedpatternmatchingstring.Forexample,thefollowingquery:
doc.bitterrootboards['*Pro Series*'].text
ReturnseverybitterrootboardselementthatcontainsthestringProSeriesanywhere withinit. Wildcard Symbols Patternmatchingstringsusedinplaceofanindexvaluecanincludethefollowing wildcards: Use this symbol * ? % \ To Matchanysequenceofzeroormorecharacters. Matchanysinglecharacter. Matchasingleword(thatis,asequenceofnonwhitespace characters). Escapetheabovemetacharacters. ExampleYouwanttoreturnallbitterrootboardselementsthat containthecharacter?.Youusethefollowingquery:
doc.bitterrootboards['\?'].text
Note: Matchstringsarecasesensitive.
49
Examples This reference

doc.name['*fourth*'].text
Returns Thetextfromallnameelementscontaining thestringfourth. Thesourcecodefromallnameelements containingthestringfourth. Theindexofeveryrowthatcontainsa stringbeginningwith199followedby anycharacterandaspace. Thetextfromeveryrowofanytable containingthestringsku. Thetextfromthesecondcellofanytable rowcontainingthestringGreen. Thetextfromthesecondcellofanyrow containingthestringGreeninthesecond table. Thetextfromthesecondcellofanyrow thatcontainsastringbeginningwithH separatedbyatleast4charactersfroma stringthatbeginswithRed.
doc.name['*fourth*'].src
doc.tr['199? *'].idx
doc.table['*sku*'].tr[].text
doc.tr['*Green*'].td[1].idx
doc.table[1].tr['*Green*'].td[1].tex t
doc.tr['*H????*Red*'].td[1].text
Regular Expressions as Index Values AsanalternativetousingwebMethodsstandardpatternmatchingsyntaxdescribed above,youcanusearegularexpressiontospecifyapatternmatchingstring.Whenyou usethismethod,youenclosetheregularexpressionin/charactersasshowninthe followingexample:

doc.bitterrootboards[/*Pro Series*/].text
ThisexamplewillreturneverybitterrootboardselementthatcontainsthestringPro Seriesanywherewithinit.Forinformationaboutregularexpressions,seethe webMethodsDeveloperUsersGuide. Attribute Matching Bydefault,matchstringsarecomparedwiththe.textpropertyofthespecifiedelements; however,youcanmatchonotherpropertiesbyspecifyingthatpropertyandamatch stringasshowninthefollowingexample.

doc.a(HREF='*webmethods.com*').src
Thisexampleextractsallhypertextlinksto*webmethods.com*. Important! Whenyouwanttosearchaspecificproperty,youmustenclosetheproperty assignmentstatementinparentheses,notbrackets.
50
Matching on the Name Attribute ElementsthatcontainaNAMEattributecanbereferenceddirectlybyname.For example,togetthetextfromallelementshavingthenamesku,youwouldusethe followingreference:

doc.sku.text
Togetthetextfromalltablecellshavingawidthvalueof8%fromallelementsnamed sku,youwouldusethefollowing:
doc.sku.td(width='8%').text
Using Masks to Extract Data Whenyouspecifyaquery,thatqueryreturnsthecompletecontentsofthespecified property.Forexample,thefollowingquery:

doc.snowboard[1].text
Returnsallofthetextfromthespecifiedsnowboardelement.Ifyouwanttoextractonlya portionofthereturnedtext,youcanapplyamasktothetextpropertytoeliminate unwantedinformation.Forexample,thefollowingobjectreference:

doc.snowboard[1].text['&list*']
Eliminatesthewordlistandeverycharacterthatfollowsit. Thefollowingtabledescribesthesymbolsyouusetoconstructamask: Use this symbol ? * % $ & \ To Eliminateasinglecharacterfromtheresult. Eliminateastringcontaininganycharacters. Eliminateasingleword(thatis,asequenceofnonwhitespace characters). Collectasinglewordandincludeitintheresult. Collectastringcontaininganycharactersandincludethatstringin theresult. Escapetheabovemetacharacters. ExampleYouwanttoreturnthetextofallsnowboardelementsin thedocument,eliminatingallasterisks(*)fromtheresults.Youuse thefollowingquery:
doc.snowboard[].text['\*']
Amaskpatternismatchedagainstthetextofanobjectreferenceuntilthepatternis exhausted,andanyremainingcharacterswillbeincludedintheresult.
51
Examples This mask

.text['&list*']
Performs the following Keepsallcharactersupto(butexcluding)thestringlist, andtheneliminatestherest. Eliminatesthefirstthreewordsintheresultandkeepsthe remainingcharacters. Eliminatesallcharactersupto(andincluding)thestring page;keepsallcharactersupto(butexcluding)thestring how;andeliminatestherest.
.text['%%%&']
.text['*page&how*']
Regular Expressions in a Mask AsanalternativetousingwebMethodsstandardmasksyntaxdescribedabove,youcan usearegularexpressiontospecifyamask.Whenyouusethismethod,youenclosethe regularexpressionin/charactersasshowninthefollowingexample:

doc.snowboard[1].text[/.list*/]
Thisexamplewilleliminatethewordlistandeverycharacterthatfollowsitfromthe result.Forinformationaboutregularexpressions,seethewebMethodsDeveloperUsers Guide. Using Lines to Select Data Ifanelementcontains<BR>tags,youcanaddresseachlineofthatelementindividually usingtheline[]array.Forexample,toreferencethethirdlineinthefollowing paragraph:
<P> The current balance for customer account<BR> 1001-233<BR> is $14,009.50<BR> as of 14:04pm 10/16/98. </P>
Youcanusethefollowingquery:
doc.p[0].line[2].text
Youcanalsoreferencelinesoftextwithina<PRE>elementinthesameway.Forexample, togetthesecondlineinthefollowingsegmentofpreformattedtext:
<PRE> ITEM 06-5449 010-13 00901R </PRE> DESC QTY 1 ITC Casing 250 #4 PVC Line 50 Tak Connector 25 UPRICE .43 23.50 3.50 TOTAL $ 107.50 $1175.00 $ 87.50
Youusethefollowingquery:
doc.pre[0].line[1].text
52
Likeotherelements,youcanusenumericrangesorpatternmatchingstringsastheindex tothelinearray. Examples This reference

doc.p[0].line[].text doc.p[0].line[1].text doc.p[0].line['*demo*'].text
Returns data from Alllinesoftextinthefirstparagraph. Thesecondlineoftextinthefirstparagraph. Alllinesoftextinthefirstparagraphthat containsthestringdemo. Lines3and9fromthefirstpreformattedtext elementinthedocument. Everyfifthlineoftextfromthefirstpreformatted textelementinthedocument.
doc.pre[0].line[2,8].text
doc.pre[0].line[0+5].text
Using Character Ranges to Extract Data Youcanuseaspecialtypeofpropertymasktoreturnaspecificrangeofcharactersfroma result.Forexample,thefollowingqueryextractsonlythefirst10charactersfromthe secondnameelement:

doc.name[1].text[0-9]
Thecombinationofcharacterrangesandlinearrayallowsyoutocreateverycomplex queriesandgivesyoutremendousflexibilityingettingspecificdatafromtextobjects.For example,thefollowingquery:

doc.pre[0].line[*connector*].text[43-50]
Getsthetextfromcolumns43through50ofanylineinthefirstpreformattedelement containingthestringconnector.
Using XQL in a Query

DataparsedfromanXMLdocumentcanbeaccessedwithaXQLquery,whichconsistsof basicURIsyntaxthatspecifieselementsintheXMLtree.Forexample,thefollowing specifiesthecollectionofpoNumelementswithinSalesOrderelements,assumingthat therootelementofthedocumentisSalesOrder:
/SalesOrder/poNum
Thecollectionofallelementswithacertaintagnameisexpressedusingthetagname itself.Thiscanbefurtherqualifiedbyindicatingthatthescopeisthecurrentcontext/, butthecurrentcontextisassumedandneednotbenotedexplicitly. Example ToselectallpoNumelements,thefollowingareequivalent:

/poNum poNum
53
Specifying a Method in XQL XQLprovidesasetofpredefinedmethodsthatyoucanusetoextractspecifickindsof informationfromanelement.Forexample,togetthetextcontainedinthefirst<poNum> elementinthefollowingexample:

<SalesOrder> <poNum>GSG-99401088</poNum>
Youusethetext()methodasfollows:
/SalesOrder/poNum[0]/text()
ThefollowingtabledescribesthesetofpredefinedmethodsinXMLQueryLanguage. Use this method

text()
To get Thetextcontainedwithinthespecifiedelement,minusanywhite spacesuchasspaces,tabs,andlinebreaks.Ifthespecifiedelement containschildelements,thecontentsofallofthoseelementsare extractedtoo. Example /SalesOrder/poNum[0]/text() Result "GSG-99401088"
rawtext()
Thetextcontainedwithinthespecifiedelement,includingany whitespace. Example If/SalesOrder/poNum[0]contains" initialthreespacesareretainedintheresult.

GSG-99401088",the
value()
Thevaluecontainedwithinthespecifiedelement.Ifthespecified elementcontainschildelements,thevaluesforallofthoseelements areextractedtoo. Example /SalesOrder/poNum[0]/value() Result "GSG-99401088"
float()
Thevaluecontainedwithinthespecifiedelement,returnedasa floatingdecimal.Thismethodisusefulincomparisons.See SpecifyingElementswithComparisonOperatorsonpage 59. Thevaluecontainedwithinthespecifiedelement,returnedasan integer.Thismethodisusefulincomparisons.SeeSpecifying ElementswithComparisonOperatorsonpage 59. Theindexnumberofthenodewithintheparent. Example /SalesOrder/poNum[0]/index() Result 0
integer()
index()
54
Use this method

nodeType()
To get Thenumberthatindicatesthetypeofnode. Example /SalesOrder/poNum[0]/nodeType() Result1 Number 1 2 3 7 8 9 Node Type Element Attribute Text PI Comment Document
namespace()
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(thevariableinthexmlnsstatementofthe document)
end()
Trueifthenodeisthelastinthecollection,relativetotheparent node.Nulliftheindexvalueisoutofrange. Example /SalesOrder/poNum[0]/end() Result true Example /SalesOrder/poNum[10]/end() Result null
Element Attributes InadditiontothepredefinedmethodsprovidedbyXQL,youcanalsospecifyanattribute nameinaquery.Whenyouspecifythe@characterandanattributename,thequery returnsthevalueofthatattribute.Forexample,inthefollowingXMLelement:

55
part[0]/@sku
ToextractthefollowingfromtheSKUattribute:
"123456"
Ifyouwanttoextractallvaluesofallattributeswithinanelement,youusetheat(@)and asterisk(*)wildcardcharacters.Thisisusefulifyouwanttotreatattributesasfieldsina Document.Forexample,inthefollowingXMLelement:

part[0]/@*
Toextractthefollowingfromthepartelement:
"Widget" "123456" "5000"
Important! Attributescannothavepathoperatorsnorindicesappendedtothemina query.Suchquerieswillresultinsyntaxerrors. Specifying Multiple Elements ToextractmultipleelementsfromanXMLdocument,youcanspecifythosenodesusing specialindexnotationasshowninthefollowingexamples.Ifyoudonotspecifyanindex number,thequeryreturnsallelements. This query
vendorNum/text( ) vendorNum[0 $to$ 2]/text( )
Returns data from AllvendorNumelementsinthedocument. ThefirstthreevendorNumelementsinthe document. vendorNumelements1,3,and7.
vendorNum[1,3,7]/text( )
Nested Element References Youcanspecifyanelementrelativetoanyoftheelementsitiscontainedwithin(thatis, relativetoitsparentcontainers).Forexample,thesecondcompanyNameelement (underscoredbelow)inthefollowingXMLfragment:
56
Partial XML document

<buyerInfo> <companyName>Global Sporting Goods</companyName> <accountNum>GSG-970414-0A</accountNum> <phoneNum>(216) 741-7566</phoneNum> <faxNum>(216) 741-7533</faxNum> <addr> <streetAddr1>10211 Brookpark Rd </streetAddr1> <city>Cleveland</city> <state>OH</state> <postalCode>22130</postalCode> </addr> <purchEmail>buyers@GSG.com</purchEmail> <purchRep>Caroline Wielman</purchRep> </buyerInfo> <supplierInfo> <companyName>Bitterroot Boards, LLC</companyName> <vendorNum>8444 99731 Q64500</vendorNum> <phoneNum>(406) 721-5000</phoneNum> <faxNum>(406) 721-5001</faxNum> <addr> <streetAddr1>Suite 441</streetAddr1> <streetAddr2>1290 Antelope Dr</streetAddr2> <city>Missoula</city> <state>MT</state> <postalCode>59801 1290</postalCode> </addr> <salesEmail>orders@GSG.com</salesEmail> <salesRep>Marc Norgaard</salesRep> </supplierInfo> <order> <lineItem> <stockNum>BK-XS160</stockNum> <desc>Extreme Spline 160 Snowboard- Black </desc> <qty>10</qty> <uPrice>149.00</uPrice> <extPrice>14900.00</extPrice> </lineItem>
Canbereferencedineitherofthefollowingways:
//companyName[1]/text() //supplierInfo[0]/companyName[0]/text()
Theindexvaluevaries,dependingonwhichparentelementsyouincludeinthe reference. Thefirstseveralcharactersarepathoperators.Youusetheseoperatorstodrilldown levelsinthedocumentyouarequerying.The/operatorbeforeanelementindicatesthe
57
immediatechild;the//operatorindicatesanydescendantfromthecurrentcontext.See theexamplesbelow. This query

//lineItem //order/lineItem
Returns data from AlllineItemelementsinthedocument. AlllineItemelementsnesteddirectlywithinallorder elementsinthedocument.
UsingWildcardCharactersforChildElements Youcanspecifyallchildelementsofaparentelementbyusinganasterisk(*)character. Seetheexamplesbelow. This query

//order/* //order/*/stockNum
Returns data from Allchildelementsofallorderelementsinthedocument. AllstockNumelementsthataregrandchildrenofanyorder elementsinthedocument.
FilteringElementsthatContainaSpecificChildElement Youcanspecifyelementsthatcontainaparticularchildelement.Seetheexamplesbelow. This query

//order[extPrice] //order[extPrice][uPri ce]
Returns data from AllorderelementsthathaveanextPricechildelement. AllorderelementsthathaveatleastoneextPriceelement andPricechildelement.
Note: YoucanalsofilterelementsusingBooleanlogic.Fordetails,seeSpecifying ElementswithBooleanExpressionsonpage 59. Using Search Strings as Index Values Youcanusepatternmatchingstringsinsteadofindexnumberstoselectmembersofan elementarray.Thistypeofqueryreturnsdatafromthoseelementswhosetextproperty matchesthespecifiedpatternmatchingstring.Forexample,thefollowingqueryreturns everycompanyNameelementthatcontainsBitterrootBoards,LLC:
//companyName[text()='Bitterroot Boards, LLC']
Youcanalsousethe/charactertospecifythetextofachildelement.Forexample,the followingqueryreturnseverysupplierInfoelementthatcontainsBitterrootBoards, LLCinthecompanyNameelementsinthedocument:

//supplierInfo[companyName/text()='Bitterroot Boards, LLC']
58
Ifyouwanttoreturnallelementsthatcontainacertainstringinanyform,youcanuse thefollowingregex(pattern)function.Forexample,thefollowingqueryreturnsthetext ofallAcctNumelementsthatcontainthestring0100anywherewithinthem:

//AcctNum[regex("0100")]/text()
Specifying Elements with Particular Namespaces Ifyouwanttofindelementsthatcontainspecificnamespaceinformation,youusethe colon:character.Forexample,thefollowingquery:

//buyerInfo:companyName[]
ReturnseverycompanyNameelementwiththenamespacebuyerInfoanywhereinthe document. Specifying Elements with Boolean Expressions Withinqueries,youcanuseBooleanexpressionstofilteroutcertainelements,selectall elementsofaparticularvalue,andselectallelementsinparticularranges.Boolean expressionsuse$and$,$or$,and$not$;however,useofthe$characterisoptionalin Developer.Seethefollowingexamples. This query
//order[extPrice and uPrice]
Returns data from AllorderelementsthathaveextPriceandPrice elements. AllorderelementsthathaveatleastoneextPriceor uPriceelementandatleastonestockNumelement. Notethatyoucanuseparenthesestosetoperation precedence.
//order[(extPrice or uPrice) and stockNum]
//order[not uPrice]
AllorderelementsthatdonotcontainuPrice elements. AllorderelementsthatcontainatleastoneextPrice elementandcontainnouPriceelements.
//order[extPrice and not uPrice]
Specifying Elements with Comparison Operators Youcanalsousecomparisonoperatorstofilteroutcertainelements,selectallelementsof aparticularvalue,andselectallelementsinparticularranges.Comparisonoperators include=,!=(notequalto),<,and>.Seethefollowingexamples. This query
//vendorNum[.='8444']
Returns data from AllvendorNumelementsinthedocumentthat equal8444. AllvendorNumelementsinthedocumentthatdo notequal8444.
//vendorNum[.!='8444']
59
This query
//vendorNum[.<'8444']
Returns data from AllvendorNumelementsinthedocumentthatare lessthan8444. AllvendorNumelementsinthedocumentthatare greaterthan8444. AllsupplierInfoelementsthatcontaina vendorNumelementthatequals8444.
//vendorNum[.>'8444']
//supplierInfo[vendorNum='844 4']
Note: Forthepurposesofcomparison,value()isimpliedifomitted.Keepinmindthat thevalueistreatedasastringunlessyouspecifyotherwise.Tocomparenumeric values,usetheinteger()orfloat()methodonbothsidesoftheexpression.For example,//uPrice[float(.)<float('9.99'). Inaddition,whenanelementreferenceisusedinacomparison,youmustonly specifyoneelementforcomparison.Forexample,//LineItem[qty>/PO/AcctNum[]]is notavalidquery,becauseallAcctNumelementsarespecifiedforcomparison.
Quick Reference: WQL vs. XQL

UsethefollowingtableasaguidelineforWQLandXQLsyntax.Fordetails,see Appendix A,webMethodsQueryLanguage. If you want Allproductelements inthedocument Thetextofthefirst nameelementwithin thefirstproduct element Allproductelements withavalueof TextContent Allproductelements withamakerattribute ofZCorp. Allmakerelements withavalueofZ Corp.withinall productelements Use this WQL statement
product[ ]
Or this XQL statement

//product
product[0].name[0].text
//product[0]/name[0]/text( )
product["TextContent"]
//product="TextContent"
product(maker="Z Corp.")
//product[@maker="Z Corp."]
product[ ].maker["Z Corp."]
//product/maker[.="Z Corp."]
60
Output from queryXMLNode

ThequeryXMLNodeserviceproducesoneoutputvariableforeachquerythatyouspecifyin theVariablestab.
Handling Errors from queryXMLNode

IfqueryXMLNodefails,itthrowsaserverexception.CommonreasonsforqueryXMLNodeto failinclude: Avariablethathasnoquerystringassignedtoit Asyntaxerrorinaquerystring AqueryfailstheAllowsNullstest Thenodevariabledoesnotexistoritisnull
Load and Query Shortcuts

Ifyouneedtocreatealoadandqueryservice(aflowthatinvokesaloadXMLNodeservice andaqueryXMLNodeservice),youcanusethewizardtobuilditforyou.Itcanquickly generatethistypeofservicebasedonaURLthatyouspecify.
Generating Default Variables

Besidesspeedandeaseofuse,thewizardoffersanotherbenefit:itcanproduceasetof defaultvariablestoextractfrequentlyusedelements(forexample,<p>,<table>,and<li>) fromanHTMLdocument.Duringdevelopment,thedefaultvariablesareusefulwaysto locateaparticularpieceofinformationinadocumentandascertainitsaddress.For example,ifyouwanttoselectinformationfromaparticulartableinadocument,youcan browsetheTablesvariabletoobtaintheindexforthattable. Thefollowingtabledescribesthesetofdefaultvariablesthewizardcanproducewhenit buildsaloadandqueryservice. Variable Name Title Anchors Paragraphs Tables Description Extractsthetextfromthedocuments<title></title>element. CollectsthevaluesofallHREFattributesinthedocument. Collectsthetextfromall<p>elementsinthedocumentandstoresitin aStringTable. Collectsthetextfromall<table>elementsinthedocumentandstores itinaStringTable.
61
Variable Name Forms Lists
Description Collectsinformationabouteach<form>elementinthedocumentand storesitinaDocumentList. Collectsthetextfromall<li>elements(fromorderedandunordered lists)inthedocumentandstoresitinaStringTable.
Important! Defaultvariablesarenotusuallyusedbytheserviceyoubuild(although youmayusethemiftheysuityourpurpose).Theyareprovidedprimarilyasguides forlocatingandexamininginformationinadocumentduringthedevelopmentstage. Youusuallydeletethedefaultvariablesafteryoufinalizethevariablelistfor queryXMLNode.
Creating a Load and Query Service from a URL

Thefollowingproceduredescribeshowtousethewizardtocreatealoadandquery serviceforaURLthatyouspecify.Whenyouusethismethod,Developergeneratesa flowservicemadeupofaloadXMLNodeservicefollowedbyaqueryXMLNodeservice,and automaticallyconfigurestheinputvariablesfortheseservicesbasedonoptionsthatyou specifyinthewizard. Afterthewizardgeneratestheloadandqueryservice,youcandoanyofthefollowing: Usetheflowasis. EdittheinputvaluesfortheloadXMLNodeand/orqueryXMLNodeservice. Insertadditionalstepsintotheflow. CopytheloadXMLNodeandqueryXMLNodeservicesintoanotherflow. To create a load and query service with the wizard 1 2 3 4 5 6 OntheFilemenu,clickNew. IntheNewdialogbox,selectFlow Service,andclickNext. IntheNew Flow Servicedialogbox,nexttoFolder,selectthefolderinwhichyouwantto savetheservice. IntheNamefield,typeanamefortheservice,andclickNext. SelectLoad and Query an HTML PageandclickNext.(Eventhoughtheoptionreferstoan HTMLdocument,youcanusethisoptionwithXMLdocuments,too.) IntheURLfield,typetheURLoftheresourceyouwanttoqueryandclickNext.(The URLyouspecifymustbeginwithhttp:or https:.) Example http://www.rubicon.com/orders/orders.html
62
Dooneofthefollowing,dependingonwhetheryouarecreatingthisserviceforan HTMLorXMLdocument:
IfyouarequeryinganHTMLdocumentandyouwantDevelopertogeneratea setofdefaultvariablesforanHTMLdocument,selectoneormoreofthe followingoptions. Select Title Anchors Paragraphs Tables Forms Lists To create AStringcontainingthetitleofthedocument. AStringListcontainingalltheHREF=valuesfromthe document. AStringListcontainingthetextofeveryparagraphinthe document. AStringListcontainingthetextfromeverytableinthe document. ADocumentListcontaininginformationabouteachformin thedocument. AStringListcontainingthetextfromallofthelistitemsin thedocument.
IfyouarequeryinganXMLdocument,clearthesettingsintheNew Flow Service dialogbox.ThedefaultvariablesgeneratedbythewizardarenotusefulforXML documents.
DooneofthefollowingdependingonwhetheryouwantDevelopertoautomatically test(execute)theserviceitbuildsforyou.
IfyouwantDevelopertoexecutetheserviceimmediatelyafteritbuildsit,select oneofthefollowingoptionsandthenclickFinish. Select Run Trace If you want Developer to RuntheservicefromDeveloperanddisplaytheresultsin theResultspanel. Runtheserviceintracemode,whichwilldisplaythe parseddocumentontheVariablestabsoyoucanuseitto developadditionalqueries. Runtheserviceinstepmode.Thiswillexecutethe loadXMLNodeserviceandthenstop.
Step
63
IfyoudonotwantDevelopertoexecutetheserviceimmediatelyafteritbuildsit, selectNoandthenclickFinish.
Important! Ifyourserviceaccessesaprotectedresource,itwillnotexecutesuccessfully usinganyoftheexecutionoptionsintheprecedingstep.Thisisbecausethe loadXMLNodeservicedoesnothavetheauthvaluesitneedstoretrievetherequested documentsuccessfully.Tocreatealoadandqueryforaprotectedresource,selectNo intheprecedingstep.Then,afterDevelopergeneratestheservice,assignthe appropriateusernameandpasswordtotheauthvariableandexecutetheservice manuallyfromtheTestmenu.
64
webMethods Query Language

66 66 69 70
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
65
A webMethods Query Language
Overview
ThewebMethodsQueryLanguage(WQL)providestheprimarymechanismformapping datafromWebdocuments.WhenaWebdocumentisreadbywebMethods,theXMLor HTMLmarkupwithinthedocumentisusedtoparsethecontentsofthedocumentinto theobjectmodel. XMLandHTMLmarkupbothconsistoftagelementsenclosedinanglebrackets:<>.In theprocessofparsing,tagelementsaretransformedintoarraysofobjects;theattributes oftagelementsbecomeobjectproperties.XMLandHTMLmarkupbothimplement containingelementsandemptyelements.Containingelementshaveopenandclosetags. Emptyelementsaresingletags. WhenaWebdocumentisparsed,thetextcontainedwithincontainingelementsbecomes thetextpropertyofthecorrespondingXMLnode. DataparsedfromWebdocumentsisaccessedwithWQLqueries,whichconsistofoneor moreindexedelementarraysandanobjectproperty.
Object References
Forthefollowingobjectreferences,xandyrepresentnumericalindexes. doc.element[x].property Anabsolutereferenceusesanumericalindexintoanelementarray. doc.element[x].element[x].property Nestedelementarraysscopetheobjectreferencetochildrenelements. doc.element[x].line[x].property Anarrayoflinesisfabricatedwhenthetextpropertyofanodecontainslinebreaks. doc.element[x].^.property Theparentofanelementisreferencedwith^. doc.element[x].?[x].property A?matchesanytypeofelementarray. doc.element[].property Emptybracketssignifythatallmembersofanelementarrayaretobereturned. doc.element|element[].property The|isusedtosignifyalogicalOR.Thecontentsoftwoormoreelementarrayscanbe returned. doc.element[x-y].property Returnsarangeofelementsfromanarray. doc.element[x-end].property endisareservedwordthatreturnsthefinalelementofanarray.
66
doc.element[x,y,z].property Returnsitemsx,y,andzwherex,y,andzrepresentnumericalindexesintoanelement array. doc.element[x+y].property Returnselementxandeveryyelementthereafter. doc.element['match'].property Returnsanarrayofelementswhosetextpropertymatchesthematchstring,whichcan containthefollowingwildcardcharacters: Use this Character * ? % \ To Matchanysequenceofzeroormorecharacters Matchanysinglecharacter. Matchesasingleword,wherewordisdefinedtobeany sequenceofnonwhitespacecharacters Escapeanyoftheabovewildcardcharacters.
Matchstringsarecomparedwiththe.textpropertyoftheindexedobject.The.text propertycontainsthetextofallchildobjects. doc.element[/RegularExpression/].property Returnsanarrayofelementswhosetextpropertymatchesthespecifiedregular expression.Forinformationabouthowtoconstructaregularexpression,seethe webMethodsDeveloperUsersGuide. doc.element(property='match').property Matchesthevalueofaspecificelementproperty.
67
Sibling Operators
WQLprovidesthefollowingsetofoperatorstorefertosiblingsofaspecifiedelement. TheexamplesshowninthesedescriptionsrefertothefollowingHTMLstructure:
TABLE TR TD B I B B TD B I B I Bold 3 Italic 1 Bold 4 Italic 2 Bold 0 Italic 0 Bold 1 Bold 2
Siblings (elements belonging to the same parent)
Thesiblingoperatorsareconstrainedbythecurrentparent.Ifanoperatorexceedsthe boundariesofthecurrentparent,anullvalueisproducedforthatreference. doc.element[x].@n.property Referencesthenthsiblingafterelement[x],regardlessoftype.Comparewith doc.element[x].+n.property,below. Example

doc.td[0].b[0].@1.text doc.td[0].i[0].@1.text doc.td[0].b[0].@4.text
Result
Italic 0 Bold 1 Null
doc.element[x].@-n.property Referencesthenthsiblingpriortoelement[x],regardlessoftype.Comparewith doc.element[x].-n.property,below. Example

doc.td[1].b[end].@-2.text doc.td[1].i[end].@-1.text doc.td[1].b[end].@-3.text
Result
Bold 3 Bold 4 Null
doc.element[x].+n.property Referencesthenthsiblingafterelement[x]thatisofthesametypeaselement[x].Compare withdoc.element[x].@n.property,above.
68
Example
doc.td[0].b[0].+1.text doc.td[0].i[0].+1.text doc.td[0].b[0].+3.text
Result
Bold 1 Null Null
doc.element[x].-n.property Referencesthenthsiblingbeforeelement[x]thatisofthesametypeaselement[x].Compare withdoc.element[x].@-n.property,above. Example

doc.td[1].b[end].-2.text doc.td[1].i[end].-1.text doc.td[1].b[end].-3.text
Result
Null Italic 1 Null
Object Properties
InadditiontothepropertiesderivedfromtheattributesofaparsedXMLorHTMLtag element,thefollowingpropertiesareavailableforallobjects: .text/.txt Returnsthetextofanobject. .value/.val Returnsthevalueofanobject.(Equivalenttothetextoftheobjectiftheelementhasno VALUEattribute.) .source/.src ReturnstheXMLorHTMLsourceofanobject. .csource/.csrc ReturnstheXMLorHTMLofthesourcegeneratedfromtheparsetreeofthedocument. .index/.idx Returnsthenumericalindexofanobject. .reference/.ref Returnsacompleteobjectreference.
69
Property Masking
Propertymaskingallowsforthestrippingawayofunwantedtextfromthevalueofan objectproperty. doc.element[x].property[x-y] Returnsarangeofcharactersfrompositionxtoy. doc.element[x].property['mask'] Useswildcardmatchingandtokencollectingtoextractdesireddatafromthevalueofan objectproperty. doc.element[x].property[/RegularExpression/] Usesaregularexpressiontoextractdesireddatafromthevalueofanobjectproperty.For informationabouthowtoconstructaregularexpression,seethewebMethodsDeveloper UsersGuide.
70
Index
Symbols
$xmldata 11
F
FTPing XML to a service 14
A
addressing document nodes 37 attributes 47, 55 NAME attribute 51 pattern matching 50
H
HTML documents extracting information from 36 retrieving from Web 21
I
index values for all members 47, 56 for multiple members 47, 56 for single member 47 specifying with pattern match 49, 58
B
Boolean expressions, using in queries 59 BR tag 52
C
character ranges 53 comparison operators using in queries 59 conventions used in this document 7
L
lines, extracting from a document 52 load and query services creating 21, 40, 62 creating from URL 62 definition of 20 loadXMLNode 21 queryXMLNode 36 shortcuts for 61 loadXMLNode creating from URL 62 data variable 25 encoding variable 31 error handling 35 failOnHTTPError variable 34 headers variable 30 input 22 isXML variable 33 loadAs variable 34 output 35 shortcuts 61 url variable 22 using 21, 62 loadXMLNode method variable 23 loadXMLNodeexpandDTD variable 32
D
Document objects as output from loadXMLNode 21 parsing 20 documentation additional 7 conventions used 7 feedback 7 documents parsing 20 retrieving from Web 21
E
emailing XML to a service 17 error handling in loadXMLNode 35 in queryXMLNode 61
71
Index
M
masks definition of 70 using in queries 51 wildcard symbols 51
N
namespace information (for services) selecting in queries 59 nodes addressing elements in 37 definition of 20 extracting information from 37 passing to queryXMLNode 36
O
object properties, definition of 45 object references definitions of 66 sibling operators 68
P
parsing documents 20 passing XML to a service 10 pattern matching in queries 49, 58 posting XML to a service 13 PRE tag 52 program code conventions in this document 7 properties 45, 69 pub.xml loadXMLNode 21 queryXMLNode 36 xmlNodeToDocument 35
for tables 49 masks 51 namespaces 59 pattern matching 49 scope 48 selecting attributes with WQL 47 attributes with XQL 55 child elements 58 lines 52 WQL properties 45 XQL methods 54 query and load services 20 queryXMLNode creating from URL 62 error handling 61 input 36 output 61 shortcuts 61 using 40, 62 using WQL with 37 using XQL with 37
R
regular expressions using in an Object reference 67, 70 retrieving documents from the Web 21
S
Sample View tab 39 scope of a query 48 sending XML documents to a service 10 via email 17, 24 via FTP 14 via HTTP 13 sibling operators 68 smtp, using to submit XML documents 17
Q
queries attributes 50, 51 Boolean expressions in 59 character ranges 53 comparison operators 59 creating by pointing 43 manually 42 definition of 20 for BR elements 52 for PRE elements 52
T
tables creating queries for 49 tabs Sample View tab 39 Variables tab 37 XML Node View tab 38
72
Index
troubleshooting information 7 typographical conventions in this document 7
Xs
XML documents and $xmldata 11 converting to IData objects 10 extracting information from 36 passing to a service 10 posting via HTTP 13 retrieving from Web 21 XML Node View tab 38 XML Query Language definition of 44 methods 54 XQL 20, 37
V
Variables tab 37
W
webMethods Query Language definition of 44 object properties 69 object references 66 overview 66 property masking 70 sibling operators 68 wildcard characters 67 wildcard characters, for WQL 67 wildcard symbols for child elements 58 for masking 51 for pattern matching 49 WQL 20, 37
73
Index
74

7-1-1 XML Services Developers Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

7-1-1 XML Services Developers Guide

Uploaded by

Copyright:

Available Formats

TitlePage

Copyright & Docu mentID

XML Services Developers Guide Version 7.1.1

XML Services Developers Guide Version 7.1.1

XML Services Developers Guide Version 7.1.1

XML Services Developers Guide Version 7.1.1

About This Guide

XML Services Developers Guide Version 7.1.1

About This Guide

XML Services Developers Guide Version 7.1.1

Submitting and Receiving XML Documents

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Submitting and Receiving XML in a String Variable

Example: Submitting XML in a String

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

import import import import public

Example: Receiving XML in a String

Submitting and Receiving XML in $xmldata

Example: Submitting and Receiving XML in $xmldata

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

import import import import

com.wm.app.b2b.client.*; com.wm.util.*; com.wm.data.*; java.io.*;

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Submitting and Receiving XML via HTTP

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Example: Submitting and Receiving XML via HTTP

Submitting and Receiving XML via FTP

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Afileextensionofxml Afileextensionwhosemimetypeisregisteredwiththeserverastext/xml. Todothis,edittheIntegrationServerslib/mime.typesfile.Forexample:

Nofileextension Toconfigureacontenthandlertohandlefilesthathavenoextension,usethe specialkeyftp_no_extensioninthelib/mime.typesfiletoindicateanull extension.Then,specifythecontenttypemappedtoanullextension.For example,thefollowingXMLcontenthandlerisusedtohandlefileswithoutan extension:

Ifyouwanttouseadifferentkeytospecifyanullextension,usetheproperty watt.net.ftp.noExtensionKeytospecifythekeyusedinlib/mime.typesto specifyafilewithnoextension.Thedefaultvalueofthispropertyis ftp_no_extension. Theservicetowhichyouwanttopassthedocumentmusttakeanodeasinput.

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

FTPing a File from a webMethods Integration Server

Receiving XML via FTP

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Submitting and Receiving XML via E-mail

Example: Sending XML via E-mail

XML Services Developers Guide Version 7.1.1

1 Submitting and Receiving XML Documents

Set this variable... from body

attachments.contenttype attachments.content OR attachments.filename

Receiving XML via E-mail

XML Services Developers Guide Version 7.1.1

Using the Load and Query Services

XML Services Developers Guide Version 7.1.1

2 Using the Load and Query Services

What Are the Load and Query Services?

XML Services Developers Guide Version 7.1.1

2 Using the Load and Query Services

Using the loadXMLNode Service

Adding loadXMLNode to a Flow Service

TypetheURL,startingwithhttp:orhttps:,andthenclickOK. Examples Thefollowingstringwouldretrievethespecifieddocumentviahttp:

XML Services Developers Guide Version 7.1.1

2 Using the Load and Query Services

Usethe SetValuemodifiertoassignvaluestotheremaininginputvariablesas needed.FormoreinformationabouttheinputvariablesforloadXMLNode,seeInputs forloadXMLNodeonpage 22.

com.wm.app.b2b.client.; com.wm.util.; com.wm.data.; java.io.;