webMethods Integration Server and webMethods Developer Documentation Supplement Version 7.1.

Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Soap Header Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up a Header Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Measuring Elapsed Time with a Consumer Handler . . . . . . . . . . . . . . . . . . . . . . . . . . About SOAP Headers in the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services for Creating and Registering Header Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 3 4 5 8 24

Introduction
webMethodsIntegrationServer7.1.2andwebMethodsDeveloper7.1.2provideanew featurethatsimplifiesthetaskofbuildingSOAPheaderhandlersforIntegrationServer basedWebservices.webMethodsIntegrationServer7.1.2alsoprovidesnewserver configurationparametersyoucanspecifyintheserverconfigurationfile. FormoreinformationaboutthefixesandenhancementsincludedinwebMethods IntegrationServer7.1.2andwebMethodsDeveloper7.1.2,seetheEnhancementsand FixesdocumentslocatedonwebMethodsAdvantage.

Building Soap Header Handlers

Note: TheinformationinthissectionsupplementsthecontentsoftheWebServices DevelopersGuide. TheservicehandlerfeaturesimplifiesthetaskofbuildingSOAPheaderhandlersfor IntegrationServerbasedWebservices.InsteadofwritingJavacodetoimplementJAX RPChandlers,youcannowcreateandcustomizeaheaderhandlerusingservice handlersandassignittoaWebServicesDescriptor(WSD)usingasetofIntegration Serverpublicservices. Note: ThepublicservicesusedtoregisterJavaJAXRPChandlerswithcustomcode remainavailable,butaredeprecatedstartingwiththisrelease.Software AG recommendsconvertingyourJAXRPChandlerstoservicehandlers,usingthe informationinthissupplement,toensuretheircompatibilityandmaintainability withcurrentwebMethodsproducts.SeethewebMethodsUpgradeGuideformore information.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Thenewservicehandlerfeatureprovidesthefollowing: Asingle,unifiedheaderhandlerthatyoucanimplementusingfloworJavaservices. Handlerpublicservicesforadministrativeandruntimetasks.

Unified Header Handler

YouimplementthebusinesslogicforservicehandlersthroughfloworJavaservicesthat youcreateto: Handlearequest Handlearesponse Handleafault TheimplementationsyoubuildwillcorrespondtotheJAXRPChandleRequest, handleResponse,andhandleFaultmethods.Notethatyoudonotneedtowrite implementationsforallthreeservicestoincludeintheheaderhandler(forexample,your headerhandlercanincludeimplementationsforhandlingarequestandhandlingafault, butnothandlingaresponse). Athandlerregistrationtime,IntegrationServeracceptsthename(s)oftheservices implementingthebusinesslogiclistedabove.Atruntime,IntegrationServerinvokesthe appropriateserviceorservicesduringhandlerprocessing.

Service Handler Public Services

Whenbuildingconsumerandproviderheaderhandlers,youusethehandlerpublic servicestodefinetheservicesthatperformtherequest,response,andfaulthandlingthat occursatinvocationtime.Thepub.soap.handlerfolder,whichispartoftheWmPublic package,contains: Administrativeservicesthatcoverregistration(andunregistration)ofthehandlers. RuntimeservicesthatallowyoutoaccessandmanipulatetheSOAPbodyorheader elementsthroughthemessagecontext.Usingtheruntimeservicesyoucan:

Addandremoveheaderelements SetandgetaSOAPmessage Setandgetpropertyvalues Deleteaproperty

Formoreinformationaboutthebuiltinservicesforwritingserviceheaderhandlers,see ServicesforCreatingandRegisteringHeaderHandlersonpage 8.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Setting Up a Header Handler

Note: TheinformationinthissectionsupplementsthecontentsoftheWebServices DevelopersGuide. Tocreateandimplementaheaderhandler,youneedtobuildtheservicesforhandlinga request,handlingaresponse,andhandlingafault.Youthenneedtoregisterthe combinationofthoseservicesasaservicebasedheaderhandler. Afteryouhavebuilttheservicesandregisteredthehandler,youcanassignthenew headerhandlertotheexistingWSDinwhichitwilloperate.

Building the Services

InDeveloper,buildtheservicestohandleyourrequest,response,andfault implementations,usingthenewhandlerruntimepublicservices.Asampleheader handlerrequestimplementation(consumer.consumerHandler:handleRequest) foraconsumer handler,withaviewofthefoldercontents,isshownbelow:

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Registering the Handler

Registerthehandleraseitheraconsumerorproviderusing pub.soap.handler:registerWmConsumerorpub.soap.handler:registerWmProvider, respectively.During registration: Youprovidealogicalnameforthehandler. YouspecifythelistofQNamesonwhichthehandleroperates. Youspecifytheservicesforhandlingarequest,aresponse,andafault asinput.

Example: Measuring Elapsed Time with a Consumer Handler

Followingisanexampleofaconsumerservicehandlerthatmeasurestheelapsedtime betweentheissuingofaSOAPrequestmessageanditsresponse.

1 Consumer handler 2
handleRequest

Web Service Consumer

3
handleResponse

Web Service Provider

Thefollowingtabledescribesthesequenceofevents. Step
1 2

Description AconsumerhandlercontainingahandleRequestandhandleResponse implementationisregisteredandassignedtoaConsumerWSD. handleRequestinvokestheservicepub.date:getCurrentDateString togetthetimeat whichtheoutgoingrequestissenttotheWebserviceprovider.handleRequest thenusessoap.handler:setPropertytoinsertthevalueintoadefinedkeynamed Timeintheclientmessagecontext. handleResponseisinvokedwhenthemessageflowreturnstotheclientside. Duringinvocation,theservicepub.date:getCurrentDateStringgetsthepresenttime, andthenusespub.soap.handler:getPropertyagainsttheTimekeytoretrievethe previouslystoredvalueinthemessagecontext. Thedifferencebetweenthetwovaluesindicatestheapproximatetimetakento executetheWebservice.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Note: Formoreinformationaboutservicehandlers,checkthedownloadablepackage WmServiceUserHandlerontheAdvantageWebsiteat http://advantage.webmethods.com.

About SOAP Headers in the Pipeline

Note: TheinformationinthissectionsupplementstheWebServicesDevelopersGuide. WhenanIntegrationServerserviceisinvokedasaWebservice,IntegrationServerplaces thecontentsoftheSOAPrequestheaderinthepipelineasadocumentnamed soapHeaders.ThesoapHeadersdocumentcontainstheelementandparameterinformation fromtheSOAPrequestheaderandallowstheheaderinformationtobepassedtothe service. ThesoapHeadersdocumentadherestothefollowinggenericstructure.

ThefollowingtabledescribesthecontentsofthesoapHeadersdocumentinthepipeline. soapHeaders DocumentAnIDatacontainingtheSOAPheaders HDRDOC1:local Name Document List Structureofaheaderelement(block) fromtheSOAPmessage.TheHDRDOC1:localName documentlistcontainsonedocumentforeachheader withthesameQName. Note: HDRDOC1representstheprefixofthefirst headerblock.localNameisaplaceholderandwillbe replacedbythelocalnameoftheheaderblock. Note: ThesoapHeadersdocumentcontainsadocument listnamedHDRDOC#:localNameforeachheader element(block)intheSOAPmessageheader. Key Description

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

ns1:fieldName

StringNameofthefirstfieldinthe headerelement(block) Note: Theprefixns1isaplaceholder andwillbereplacedbytheprefixof thechildelementoftheheader element(block).Likewise,fieldName isaplaceholderandwillbereplaced bythelocalnameofthefirstchild elementcontainedintheheader element(block).

nsDecls

DocumentNamespacesassociated withanynamespaceprefixesthatare usedinthechildelementnamesin HDRDOC1:localName.Eachentryin nsDeclsrepresentsanamespace prefix/URIpair,whereakeyname representsaprefixandthevalueof thekeyspecifiesthenamespaceURI. Key ns1 Description StringNamespace declarationassociated withtheprefixns1,where ns1isaplaceholderand willbereplacedbythe prefixusedwiththefirst childelementofthe headerelement(block).

nsDecls

DocumentNamespacesassociatedwithany namespaceprefixesusedbytheheaderelements (blocks). Note: Thisdocumentwillcontainachildstring namedHDRDOC#foreachnamespaceprefixused withaheaderelement(block). Key HDRDOC1 Description StringNamespacedeclaration associatedwiththeprefix HDRDOC1.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Example of SOAP Headers in the Pipeline

Forexample,supposethatanISserviceinvokedasaWebservicereceivedthisSOAP request:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header> <pfx1:firstHdrElement xmlns:pfx1=namespace1 xmlns:hdr1ns=ns1namespace> <hdr1ns:firstField>Value of firstField in firstHdr</hdr1ns:firstField> </pfx1:firstHdrElement> <pfx2:secondHdrElement xmlns:pfx2=namespace2 xmlns:hdr2ns=ns2namespace> <hdr2ns:firstField>Value of firstField in secondHdr</hdr2ns:firstField> </pfx2:secondHdrElement> </SOAP-ENV:Header> <SOAP-ENV:Body> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope>

IntegrationServercreatesasoapHeadersdocumentthatlookslikethisandaddsittothe inputpipelineoftheISservice:

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Services for Creating and Registering Header Handlers

Note: TheinformationinthissectionsupplementsthewebMethodsIntegrationServer BuiltInServicesReference. IntegrationServerprovidesnewbuiltinservicesthatyoucanuseto: Definethesignatureofheaderhandlerservices. Retrieve,remove,andaddheaderelements. Retrieve,remove,orsetpropertiesinthemessagecontext. RetrieveorreplacetheSOAPmessageinthemessagecontext. Registeragroupofheaderhandlerservicesasaconsumerorproviderhandler. IntegrationServeralsoprovidesservicesforlookingupuniversalnamesfordocument types. Note: Youcanstillusethefollowingpublicservices,whichwereavailableforusewith JAXRPChandlerswithcustomcode,tounregisterorlistprovidersandconsumers: pub.soap.handler:unregisterProvider pub.soap.handler:unregisterConsumer pub.soap.handler:listProvider pub.soap.handler:listConsumer Formoreinformationabouttheseservices,seethewebMethodsIntegrationServerBuilt InServicesReference. Thefollowingtableliststhenewelementsforcreatingheaderhandlersandworkingwith universalnames. Element pub.soap.handler:addHeaderElement pub.soap.handler:getHeaderElement pub.soap.handler:getProperty pub.soap.handler:getSOAPMessage pub.soap.handler:handlerSpec pub.soap.handler:registerWmConsumer Description WmPublic.InsertsadocumentintoaSOAP messageasanewheaderelement(block). WmPublic.Retrievesaheaderelementfroma SOAPmessage. WmPublic.Getsthevalueofaspecifiedproperty fromamessagecontext. WmPublic.GetstheSOAPmessagefromagiven messagecontext. WmPublic.Specificationtouseasthesignature foraservicethatactsasaheaderhandler. WmPublic.Registersaheaderhandlerforuse withconsumerWebservicedescriptors.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

Element pub.soap.handler:registerWmProvider pub.soap.handler:removeHeaderElement pub.soap.handler:removeProperty pub.soap.handler:setProperty pub.soap.handler:setSOAPMessage pub.universalName:findDocumentType

Description WmPublic.Registersaheaderhandlerforuse withproviderWebservicedescriptors. WmPublic.Removesaheaderelement(block) fromaSOAPmessage. WmPublic.Removesapropertyfromamessage context. WmPublic.Setsthevalueofaspecificpropertyin amessagecontext. WmPublic.SetstheSOAPmessageinamessage context. WmPublic.Returnsthefullyqualifieddocument typenameforaprovidedexplicituniversal name. WmPublic.Returnsthecontentsofthecurrent universalnameregistry,includingservicesand documenttypes.

pub.universalName:listAll

Note: Thefollowingservicesaredeprecated:pub.soap.handler:registerConsumerand pub.soap.handler:registerProvider.

pub.soap.handler:addHeaderElement
WmPublic.InsertsadocumentintoaSOAPmessageasanewheaderelement(block). Input Parameters messageContext Object MessagecontextcontainingtheSOAPmessagetowhichto addaheaderelement. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreatesthe messagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext,whichenablesyoutousethe messagecontexttopassinformationamonghandlers.

ISDEV-DS-712-20080926

webMethods Integration Server and webMethods Developer Version 7.1.2

QName

DocumentOptional.Qualifiedname(namespacenameandlocal name)oftheheaderelementtoadd. TheQNamedocumentreferencesthepub.soap.utils:QNamedocument type.Formoreinformationaboutpub.soap.utils:QName,seethe webMethodsIntegrationServerBuiltInServicesReference. Note: IfyoudonotspecifyQNamevalue,youmustspecify documentType.

headerDocument

Document Documenttoaddasaheaderelement.IntegrationServer convertsthedocumenttoanXMLnodeandinsertsitasachild elementoftheheaderelementspecifiedinQName. StringOptional.NameoftheISdocumenttypethatspecifiesthe structureandnamespacesofthedocumenttouseasanewheader element.IntegrationServerusestheuniversalnameassignedtothe ISdocumenttypetodeterminethequalifiednametouseforthe newheaderelement.IfyouspecifydocumentType,headerDocument mustbeainstanceofthisdocumenttype. Note: IfyoudonotspecifydocumentType,youmustspecifyQName.

documentType

mustUnderstand

String Optional.SetsthevalueofthemustUnderstandattributefor thenewheaderelement(block).ThemustUnderstandattribute specifieswhetherrecipients(theactororroleatwhichtheheaderis targeted)arerequiredtoprocessaheaderentry.Recipientsthat cannotprocessamandatoryheaderentrymustrejectthemessage andreturnaSOAPfault. Set to...

true false

To... Indicatethatprocessingtheheaderentryisoptional. Indicatethatprocessingtheheaderentryismandatory.

Thereisnodefaultvalue. IfyoudonotsetmustUnderstand,IntegrationServeromitsthe mustUnderstandattributefromtheheaderentry,whichis equivalenttosettingmustUnderstandtofalse. Note: InSOAP1.2,thevaluesofthemustUnderstandattribute changedfrom0and1toTrueandFalse;however,IntegrationServer processesbothsetsofvaluesthesameandperformsanynecessary conversions.

ISDEV-DS-712-20080926

10

webMethods Integration Server and webMethods Developer Version 7.1.2

actor

String Optional.Targetoftheheaderentry.Thevalueofactor determinesthevalueoftheactororroleattributefortheheader entry.TheactororroleattributespecifiesaURIfortherecipientofa headerentry. Ifyoudonotspecifyavalueforactor,theactororroleattributewill beblankintheSOAPheader.InSOAP1.1,thisindicatesthatthe recipientistheultimatedestinationoftheSOAPmessage.InSOAP 1.2,thisisequivalenttosupplyingthatattributewiththevalue http://www.w3.org/2003/05/soapenvelope/role/ultimateReceiver. Note: InSOAP1.2,theactorattributeisnamedrole;however, IntegrationServerprocessesbothnamesthesameandperformsany necessaryconversions.

Output Parameters None. Usage Notes QNameanddocumentTypearemutuallyexclusive.Eventhoughtheparametersare optional,youmustspecifyoneortheother.Ifyoudonotspecifyeither,Integration Serverdisplaysthefollowingerror:

[ISS.0088.9422] One of the mutually exclusive parameter QName or documentType is missing or invalid.

IfyouspecifyvaluesforQNameanddocumentType,IntegrationServerusestheQName valueandignoresdocumentType. FormoreinformationaboutthemustUnderstandandactorattributesinSOAP1.1, seetheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08May2000at http://www.w3.org/TR/SOAP/. FormoreinformationaboutthemustUnderstandandroleattributesinSOAP1.2,see theSimpleObjectAccessProtocol(SOAP)1.2specificationat http://www.w3.org/TR/SOAP12/. Example SupposethatmessageContextcontainsaSOAPmessagewithanemptySOAPheader andyouwanttoaddaheaderelementbypassingthepub.soap:handler:addHeaderElement servicethefollowinginputparameters: Input Parameter QName Provided Value namespaceName localName
userHandlerNamespaceName userHandlerLocalName

ISDEV-DS-712-20080926

11

webMethods Integration Server and webMethods Developer Version 7.1.2

Input Parameter headerDocument

Provided Value AninstanceofdocumentTypes:myNewHeader,whichcontainsa singlefieldoftypeStringnamedmyString.Thevalueof myStringis:Value of myString field.

documentType mustUnderstand actor

Notprovided.
true soapActor

Executionofthepub.soap.handler:addHeaderElementserviceresultsinthisSOAPheader forSOAP1.1:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <HDR:userHandlerLocalName xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:HDR="userHandlerNamespaceName" SOAP-ENV:actor="soapActor" SOAP-ENV:mustUnderstand="1"> <myString>Value of myString field.</myString> </HDR:userHandlerLocalName> </SOAP-ENV:Header> <SOAP-ENV:Body> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope>

IntegrationServerusesHDRasthenamespaceprefixforthenamespacenameofthe header. See Also pub.soap.handler:getHeaderElement pub.soap.handler:removeHeaderElement

ISDEV-DS-712-20080926

12

webMethods Integration Server and webMethods Developer Version 7.1.2

pub.soap.handler:getHeaderElement
WmPublic.RetrievesaheaderelementfromaSOAPmessage. Input Parameters messageContext ObjectMessagecontextcontainingtheSOAPmessagefromwhichto retrieveaheaderelement. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreatesthe messagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext,whichenablesyoutousethemessage contexttopassinformationamonghandlers. QName DocumentOptional.Qualifiedname(namespacenameandlocal name)oftheheaderelementtoretrieve. TheQNamedocumentreferencesthepub.soap.utils:QNamedocument type.Formoreinformationaboutpub.soap.utils:QName,seethe webMethodsIntegrationServerBuiltInServicesReference. IfyoudonotspecifyQName,youmustspecifydocumentType. documentType String Optional. FullyqualifiednameoftheISdocumenttypethat specifiesthestructuretoimposeontheresultingdocument. IntegrationServerusestheexplicituniversalnameassignedtothe documenttypetodeterminewhichheaderelementtoretrievefrom theSOAPmessage. IfyoudonotspecifydocumentType,youmustspecifyQName. Output Parameters outputHeaderDocument Usage Notes QNameanddocumentTypearemutuallyexclusive.Eventhoughtheparametersare optional,youmustspecifyoneortheother.Ifyoudonotspecifyeither,Integration Serverdisplaysthefollowingerror:
[ISS.0088.9422] One of the mutually exclusive parameter QName or documentType is missing or invalid.

Document HeaderelementfromtheSOAPmessageinthe formofadocument(IData).

IfyouspecifyvaluesforQNameanddocumentType,IntegrationServerusesQName andignoresdocumentType.

ISDEV-DS-712-20080926

13

webMethods Integration Server and webMethods Developer Version 7.1.2

Example SupposethatmessageContextcontainsaSOAPmessagewiththefollowingheader:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="userHandlerNamespaceName" xmlns:pfx="pfx1namespace" xmlns:ns1="ns1namespace" xmlns:ns2="ns2namespace"> <SOAP-ENV:Header> <user:userHandlerLocalName> <pfx:myLocalName> <ns1:myField> <ns2:myFieldValue>someValue</ns2:myFieldValue> </ns1:myField> </pfx:myLocalName> </user:userHandlerLocalName> </SOAP-ENV:Header> <SOAP-ENV:Body> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Additionally,supposethatpub.soap:handler:getHeaderElementusesthefollowinginput values,wheremessageContexthasalreadybeenobtained: Input Parameter QName documentType Provided Value namespaceName localName
userHandlerNamespaceName userHandlerLocalName

documentTypes:myHeaderStructure ThestructureofdocumentTypes:myHeaderStructurelookslikethis:

TheprefixesindocumentTypes:myHeaderStructurerefertothe followingnamespaces. Prefix Namespace

ISDEV-DS-712-20080926

14

webMethods Integration Server and webMethods Developer Version 7.1.2

Input Parameter

Provided Value myPrefix myNS1 myNS2

pfx1namespace ns1namespace ns2namespace

Executionofthepub.soap.handler:getHeaderElementserviceresultsinthefollowingvalue foroutputHeaderDocument:

IntegrationServerusesthefollowingconventionsinoutputHeaderDocument:

outputHeaderDocumentalwayscontainsadocumentlistnamed HDRDOC1:localName.Thedocumentlistcontainstheheaderretrievedbythe pub.soap.handler:getHeaderElement service. IntegrationServerusesHDRDOC1astheprefixfortheheaderelement(block). ThevalueofHDRDOC1isthenamespacenameportionoftheQName.The outputHeaderDocument/nsDeclsdocumentidentifiesthenamespaceassociated withthenamespaceprefixoftherequestedheaderelement(block). TheHDRDOC1:localName[0]documentcontainsannsDeclsdocumentthat identifiesthenamespaceprefixesusedwithintheretrievedheaderelement. IntegrationServerreplacestheprefixesusedintheSOAPenvelopewiththe prefixesthatthedocumenttypespecifiesforthesamenamespaces.

IntegrationServerusesthesamegeneralstructurewhenplacingSOAPheadersinthe pipelineforISservicesactingasWebservices.Formoreinformation,seeServer ConfigurationParametersonpage 24. See Also pub.soap.handler:addHeaderElement pub.soap.handler:removeHeaderElement

ISDEV-DS-712-20080926

15

webMethods Integration Server and webMethods Developer Version 7.1.2

pub.soap.handler:getProperty
WmPublic.Getsthevalueofaspecifiedpropertyfromamessagecontext. Input Parameters messageContext ObjectMessagecontextfromwhichtoretrieveapropertyvalue. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreatesthe messagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext,whichenablesyoutousethemessage contexttopassinformationamonghandlers.Forexample,inachain ofrequestheaderhandlers,thefirstrequestheaderhandlercouldset amessagepropertythatthesecondrequestheaderhandlerretrieves. key Output Parameters value See Also pub.soap.handler:removeProperty pub.soap.handler:setProperty ObjectValueofthespecifiedproperty. String Nameoftheselectedpropertywhosevaluetoretrieve.

pub.soap.handler:getSOAPMessage
WmPublic.GetstheSOAPmessagefromagivenmessagecontext. Input Parameters messageContext Object MessagecontextfromwhichtogettheSOAPmessage. AmessagecontextcontainspropertiesfortheSOAPmessage andprovidesaccesstotheSOAPmessage.IntegrationServer createsthemessagecontextandpassesittotheheaderhandler. AllhandlersinvokedbyagiveninstanceofaSOAPrequestor SOAPresponseusethesamemessagecontext,whichenables youtousethemessagecontexttopassinformationamong handlers. Output Parameters SOAPMessage Object Objectoftypejavax.xml.soap.SOAPMessagethat representstheSOAPmessage.

ISDEV-DS-712-20080926

16

webMethods Integration Server and webMethods Developer Version 7.1.2

Usage Notes YoucanusetheSOAPmessageretrievedbythisservicewithanyexistingpublic servicethattakesanobjectoftypejavax.xml.soap.SOAPMessageasinput.For example,youcanusetheSOAPmessageasinputforthepub.soap.utils:addBodyEntryor pub.soap.utils:addHeaderEntryservices. See Also pub.soap.handler:setSOAPMessage

pub.soap.handler:handlerSpec
WmPublic.Specificationtouseasthesignatureforaservicethatactsasaheaderhandler. Input Parameters messageContext Object Messagecontexttobeprocessedbytheheaderhandler. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreates themessagecontextandpassesittotheheaderhandler.All handlersinvokedbyagiveninstanceofaSOAPrequestorSOAP responseusethesamemessagecontext,whichenablesyoutouse themessagecontexttopassinformationamonghandlers. Output Parameters statusCode String Indicateswhethertheheaderhandlerserviceexecuted successfullyornot.ThestatusCodeparametermusthaveoneof thefollowingvalues: Value
0 1

Description Indicatesthehandlerserviceexecutedsuccessfully. Indicatesthehandlerserviceendedinfailureandno exceptionwillbethrown. Indicatesthatthehandlerserviceendedinfailureand threwtheexceptionjavax.xml.rpc.JAXRPCException. Indicatesthatthehandlerserviceendedinfailureand threwtheexceptionjavax.xml.rpc.soap.SOAPFault.

faultMessage

StringConditional.Textofthefaultmessagesentifanexception occurredduringhandlerexecution.ThefaultMessageoutput parameterisproducedwhenstatusCodeis2or3.

ISDEV-DS-712-20080926

17

webMethods Integration Server and webMethods Developer Version 7.1.2

Usage Notes Servicesthatactasheaderhandlersdonotneedtousethisspecificationtodefinethe signatureoftheservice.However,servicesthatactasheaderhandlersmusttakethe inputparametersandproducetheoutputparametersidentifiedinthisspecification. IfstatusCodedoesnotcontainoneofthespecifiedvalues,IntegrationServerassumes avalueof0. Atruntime,ifstatusCodeissettoavalueof2or3,IntegrationServerinvokesthe serviceyouspecifiedforhandlingfaults(handleFaultService)whenyouregisteredaset ofservicesasaconsumerorproviderheaderhandler.Forinformationabout registeringaconsumerheaderhandler,seepub.soap.handler:registerWmConsumeron page 18.Forinformationaboutregisteringaproviderheaderhandler,see pub.soap.handler:registerWmProvideronpage 19.

pub.soap.handler:registerWmConsumer
WmPublic.RegistersaheaderhandlerforusewithconsumerWebservicedescriptors. Input Parameters descriptiveName QNameList String Nametoassigntotheconsumerheaderhandler.Each consumerheaderhandlermusthaveauniquename. Document ListQualifiednamesoftheheadersonwhichthe handleroperates.Inthedocumentlist,eachdocument referencesthepub.soap.utils:QNamedocumenttype. StringOptional.Fullyqualifiednameoftheservicetouseas therequestheaderhandler. StringOptional.Fullyqualifiednameoftheservicetouseas theresponseheaderhandler. StringOptional.Fullyqualifiednameoftheservicetouseas thefaultheaderhandler.

handleRequestService handleResponseService handleFaultService Output Parameters None. Usage Notes

Beforeyouregisteraconsumerheaderhandler,createtheservicesthatwillactasthe request,response,andfaultheaderhandlers. IntegrationServerstoresinformationaboutregisteredheaderhandlersinmemory. IntegrationServerdoesnotpersistregisteredheaderhandlerinformationacross restarts.Consequently,youmustregisterheaderhandlerseachtimeIntegration Serverstarts.Toaccomplishthis,createaservicethatregistersaheaderhandlerand makethatserviceastartupserviceforthepackagethatcontainstheservicesthatact asheaderhandlers.

ISDEV-DS-712-20080926

18

webMethods Integration Server and webMethods Developer Version 7.1.2

YoucanuseaconsumerheaderhandlerwithconsumerWebservicedescriptorsonly. Usethepub.soap.handler:registerWmProviderservicetoregisteraheaderhandlerforuse withproviderWebservicedescriptors. Tounregisteraconsumerheaderhandler,usethepub.soap.handler:unregisterConsumer service.Formoreinformationaboutthisservice,seethewebMethodsIntegrationServer BuiltInServicesReference. IfyouspecifyaservicethatdoesnotexistforhandleRequest,handleResponse,or handleFaultService,IntegrationServerthrowsthiserror:

[ISS.0088.9421] The Service serviceName does not exist or invalid

IfaregisteredhandlerwiththesamedescriptiveNamealreadyexists,Integration Serverthrowsthiserror.
ISS.0088.9156 JAX Handler <handlerName> already registered

See Also pub.soap.handler:registerWmProvider

pub.soap.handler:registerWmProvider
WmPublic.RegistersaheaderhandlerforusewithproviderWebservicedescriptors. Input Parameters descriptiveName QNameList String Nametoassigntotheproviderheaderhandler.Each providerheaderhandlermusthaveauniquename. Document ListQualifiednamesoftheheadersonwhichthe handleroperates.Inthedocumentlist,eachdocument referencesthepub.soap.utils:QNamedocumenttype. StringOptional.Fullyqualifiednameoftheservicetouseas therequestheaderhandler. StringOptional.Fullyqualifiednameoftheservicetouseas theresponseheaderhandler. StringOptional.Fullyqualifiednameoftheservicetouseas thefaultheaderhandler.

handleRequestService handleResponseService handleFaultService Output Parameters None. Usage Notes

Beforeyouregisteraproviderheaderhandler,createtheservicesthatwillactasthe request,response,andfaultheaderhandlers.

ISDEV-DS-712-20080926

19

webMethods Integration Server and webMethods Developer Version 7.1.2

IntegrationServerstoresinformationaboutregisteredheaderhandlersinmemory. IntegrationServerdoesnotpersistregisteredheaderhandlerinformationacross restarts.Consequently,youneedtoregisterheaderhandlerseachtimeIntegration Serverstarts.Toaccomplishthis,createaservicethatregistersaheaderhandlerand makethatserviceastartupserviceforthepackagethatcontainstheservicesthatact asheaderhandlers. YoucanuseaproviderheaderhandlerwithproviderWebservicedescriptorsonly. Usethepub.soap.handler:registerWmConsumerservicetoregisteraheaderhandlerforuse withconsumerWebservicedescriptors. Tounregisteraproviderheaderhandler,usethepub.soap.handler:unregisterProvider service.Formoreinformationaboutthisservice,seethewebMethodsIntegrationServer BuiltInServicesReference. IfyouspecifyaservicethatdoesnotexistforhandleRequest,handleResponse,or handleFaultService,IntegrationServerthrowsthiserror:
[ISS.0088.9421] The Service <serviceName> does not exist or invalid

IfaregisteredhandlerwiththesamedescriptiveNamealreadyexists,Integration Serverthrowsthiserror.
[ISS.0088.9156] JAX Handler <handlerName> already registered

See Also pub.soap.handler:registerWmConsumer

pub.soap.handler:removeHeaderElement
WmPublic.Removesaheaderelement(block)fromaSOAPmessage. Input Parameters messageContext Object MessagecontextthatcontainstheSOAPmessagefromwhich toremoveaheaderelement(block). AmessagecontextcontainspropertiesfortheSOAPmessageaswell asprovidingaccesstotheSOAPmessage.IntegrationServercreates themessagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext.Thisenablesyoutousethemessage contexttopassinformationbetweenhandlers. QName ObjectQualifiednameoftheheaderelement(block)toremove.The QNamedocumentreferencesthepub.soap.utils:QNamedocumenttype. Formoreinformationaboutpub.soap.utils:QName,seethewebMethods IntegrationServerBuiltInServicesReference.

ISDEV-DS-712-20080926

20

webMethods Integration Server and webMethods Developer Version 7.1.2

Output Parameters status String IndicateswhetherIntegrationServersuccessfullyremovedthe headerelement. Key

True

Description IndicatesthatIntegrationServerremovedtheheader element. IndicatesthatIntegrationServerdidnotremovethe headerelementbecausetheSOAPmessagedidnot containaheaderelementthatmatchedtheprovided QName.

False

See Also pub.soap.handler:addHeaderElement pub.soap.handler:getHeaderElement

pub.soap.handler:removeProperty
WmPublic.Removesapropertyfromamessagecontext. Input Parameters messageContext ObjectMessagecontextfromwhichtoremoveaproperty. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreatesthe messagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext,whichenablesyoutousethemessage contexttopassinformationamonghandlers.Forexample,inachain ofrequestheaderhandlers,thefirstrequestheaderhandlercouldset amessagepropertythatthesecondrequestheaderhandlerretrieves. key Output Parameters None. See Also pub.soap.handler:getProperty pub.soap.handler:setProperty String Nameofthepropertytoremove.

ISDEV-DS-712-20080926

21

webMethods Integration Server and webMethods Developer Version 7.1.2

pub.soap.handler:setProperty
WmPublic.Setsthevalueofaspecificpropertyinamessagecontext. Input Parameters messageContext Object Messagecontextinwhichtosetaproperty. AmessagecontextcontainspropertiesfortheSOAPmessageand providesaccesstotheSOAPmessage.IntegrationServercreatesthe messagecontextandpassesittotheheaderhandler.Allhandlers invokedbyagiveninstanceofaSOAPrequestorSOAPresponse usethesamemessagecontext,whichenablesyoutousethemessage contexttopassinformationamonghandlers.Forexample,inachain ofrequestheaderhandlers,thefirstrequestheaderhandlercouldset amessagepropertythatthesecondrequestheaderhandlerretrieves. key value Output Parameters None. See Also pub.soap.handler:getProperty pub.soap.handler:removeProperty String Nameofthepropertytoset. ObjectValuetoassigntothespecifiedproperty.

pub.soap.handler:setSOAPMessage
WmPublic.SetstheSOAPmessageinamessagecontext. Input Parameters messageContext Object MessagecontextinwhichtosettheSOAPmessage. AmessagecontextcontainspropertiesfortheSOAPmessage andprovidesaccesstotheSOAPmessage.IntegrationServer createsthemessagecontextandpassesittotheheaderhandler. AllhandlersinvokedbyagiveninstanceofaSOAPrequestor SOAPresponseusethesamemessagecontext,whichenables youtousethemessagecontexttopassinformationamong handlers. SOAPMessage Object Objectoftypejavax.xml.soap.SOAPMessagetouseto overwritetheexistingSOAPmessageinthemessagecontext.

ISDEV-DS-712-20080926

22

webMethods Integration Server and webMethods Developer Version 7.1.2

Output Parameters None. Usage Notes Usethisservicewithcaution,asitoverwritestheentireSOAPmessage,includingthe SOAPheader,body,andfault. See Also pub.soap.handler:getSOAPMessage

pub.universalName:findDocumentType
WmPublic.Returnsthefullyqualifieddocumenttypenameforaprovidedexplicit universalname. Input Parameters namespaceName localName Output Parameters svcName StringConditional.Fullyqualifiednameofthedocumenttype associatedwiththeuniversalnameinnamespaceNameand localName.Ifthespecifieduniversalnameisnotintheregistry, svcNamewillbenull. StringNamespaceportionoftheuniversalname. StringLocalnameportionoftheuniversalname.

pub.universalName:listAll
WmPublic.Returnsthecontentsofthecurrentuniversalnameregistry,including servicesanddocumenttypes. Input Parameters None.

ISDEV-DS-712-20080926

23

webMethods Integration Server and webMethods Developer Version 7.1.2

Output Parameters names Document ListEntriesintheuniversalnameregistry.Eachdocument (IDataobject)inthelistrepresentsanentryintheuniversalname registry. Thereisoneentryforeveryexplicituniversalnamethathasbeen definedontheserver.Implicituniversalnamesarenotmaintained intheregistry. Eachdocumentinthelistcontainsthefollowinginformation: Key universalName Description DocumentUniversalnameassociatedwiththeentry. Thisdocumentcontainsthefollowinginformation: Key namespaceName localName svcName Description StringNamespaceportionofthe universalname. StringLocalportionofthe universalname.

StringFullyqualifiedwebMethodsservicenameor documenttypenameassociatedwiththeentry(for example,gl.post:postEntry).

Usage Notes Toreturnalistoftheservicesintheuniversalnameregistryonly,usethe pub.universalName:list service.

Server Configuration Parameters

Note: TheinformationinthissectionsupplementsthecontentsofAppendixB:Server ConfigurationParametersinthewebMethods Integration Server Administrators Guide . webMethodsIntegrationServer7.1.2includesthefollowingnewserverparameters. watt.server.acl.groupScanInterval Specifies,inmilliseconds,howfrequentlyIntegrationServerchecksfortheMy webMethodsServeruserdatabaseandattemptstoloadcentralusermanagementgroups assignedtoanACL.Thedefaultis10,000milliseconds. watt.server.jdbc.derby.commitTolerance Specifies,inmilliseconds,howlongtheDerbysoftwarewillwaitforacommittoprocess. Thedefaultis150milliseconds.

ISDEV-DS-712-20080926

24

webMethods Integration Server and webMethods Developer Version 7.1.2

watt.server.soap.validateResponse EnablesordisablesSOAPresponsevalidation.Whensettotrue,IntegrationServer validatestheSOAPresponsereceivedbyaWebserviceconnector.Whensettofalse, IntegrationServerdoesnotvalidatethereceivedSOAPresponse.Thedefaultistrue. watt.server.SoapRPC.useSecondaryType InstructsIntegrationServertouseasecondtypedefinitionwhencreatingtheSOAP responseforaservicewhoseinputoroutputsignaturescontainidenticallynamed variablesofdifferenttypes.WhencreatingaWSDLfromaproviderWebService Descriptorthatcontainsaservicewithidenticallynamedfieldsofdifferenttypes, IntegrationServerrenamesthesecondinstanceofthefieldtypeintheWSDL.Atrun time,forRPCEncodedSOAPbinding,IntegrationServerencodesthetypesintheSOAP response.Whenthispropertyissettotrue,theSOAPresponsereferstotherenamedtype definition.Whensettofalse,theSOAPresponsereferstotheoriginaltypedefinition insteadoftherenamedone.Thedefaultisfalse.ThispropertyisapplicabletoRPC EncodedSOAPbindingonly. watt.server.trigger.suspendOnAuditErrorWhen SpecifieswhenIntegrationSevershouldsuspendatrigger.Atriggercanbesuspended whenboththefollowingoccur: Thetriggerservicefails. Thetriggerservicecannotwriteauditdatatotheauditdatabasebecauseanaudit exceptionoccurs. WhenIntegrationServersuspendsatrigger,ithaltsdocumentprocessinganddocument retrievalforthetrigger.SuspendingthetriggerpreventsIntegrationServerfrom acknowledgingthedocumentandpreventstheBrokerfromdiscardingthedocument. Aftersuspendingthetrigger,IntegrationServermonitorstheconnectiontotheaudit databaseandresumesthetrigger(documentprocessinganddocumentretrieval)when theconnectiontotheauditdatabaseisreestablished.IntegrationServerretrievesthe unacknowledgeddocumentfromtheBrokerandattemptstoprocessitagain. Setthewatt.server.trigger.suspendOnAuditErrorWhenparametertooneofthefollowing values: Specify...
Never

To... IndicatethatIntegrationServerdoesnotsuspendatriggerif thetriggerserviceendsbecauseofanerrorandanaudit exceptionoccurswhenthetriggerserviceattemptstowrite datatotheauditdatabase.

ISDEV-DS-712-20080926

25

webMethods Integration Server and webMethods Developer Version 7.1.2

Specify...
Error

To... IndicatethatIntegrationServersuspendsatriggerifthe triggerserviceendsbecauseofanerrorandanaudit exceptionoccurswhenthetriggerserviceattemptstowrite datatotheauditdatabase. IndicatethatIntegrationServersuspendsatriggerifthe triggerserviceendsbecauseofanerror,thetriggerserviceis configuredtoincludetheservicepipelineintheauditlog, andanauditexceptionoccurswhenthetriggerservice attemptstowritedatatotheauditdatabase.Thedefaultis ErrorPipelineEnabled.

ErrorPipelineEnabled

IntegrationServermustberestartedforanychangestothisparametertotakeeffect. Thewatt.server.trigger.suspendOnAuditErrorWhenconfigurationparameteronly applieswhentheauditsubsystemisconfiguredtowritedatasynchronously (watt.server.auditSync=true).

ISDEV-DS-712-20080926

26