You are on page 1of 236

TitlePage

Developer

Version 7.1

Publish-Subscribe Developers Guide

Copyright & Docu mentID

Cerebra,Glue,InfravioXBroker,InfravioXRegistry,Infravio,MywebMethodsServer,MywebMethods,webMethodsAccess,webMethodsAdministrator, webMethodsBroker,webMethodsCentralConfiguration,webMethodsDashboard,webMethodsDesigner,webMethodsDeveloper,webMethodsFabric, webMethodsGlue,webMethodsInfrastructureDataCollector,webMethodsInfravioXBroker,webMethodsInfravioXRegistry,webMethodsInstaller, webMethodsIntegrationServer,webMethodslogo,webMethodsMainframe,webMethodsManager,webMethodsModeler,webMethodsMonitor, webMethodsOptimizeforInfrastructure,webMethodsOptimizeforProcess,webMethodsOptimize,webMethodsPortal,webMethodsProcessEngine, webMethodsServicenet,webMethodsTaskEngine,webMethodsTradingNetworks,webMethodsWorkflow,andwebMethodsareeitherregistered trademarksortrademarksofwebMethods,Inc. Acrobat,Acrobat,andReaderareregisteredtrademarksofAdobeSystemsIncorporated.AmdocsandClarifyCRMareregisteredtrademarksofAmdocs. AribaisaregisteredtrademarkofAriba,Inc.BEA,BEAWebLogicServer,Jolt,andTuxedoareregisteredtrademarks,andBEAWebLogicPlatformisa trademarkofBEASystems,Inc.ActionRequestSystem,BMCSoftware,PATROL,andRemedyareregisteredtrademarksofBMCSoftware,Inc.BroadVision isaregisteredtrademarkofBroadVision,Inc.ChemeStandardsandCIDXaretrademarksofCIDX,TheChemicalIndustryDataExchange.SiteMinderand UnicenterareregisteredtrademarksofCA,Inc.PopChartisaregisteredtrademarkofCORDATechnologies,Inc.KenanandArborareregisteredtrademarks ofAlcatelLucent.DataConnectionandSNAPIXareregisteredtrademarksofDataConnectionCorporation.D&BandDUNSareregisteredtrademarksof Dun&BradstreetCorporation.EclipseisatrademarkofEclipseFoundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregistered trademarkoftheEuropeanUnionandtheUnitedStates.FinancialInformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd. UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCandTransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PA RISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isaregisteredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2, Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,and z/OSareregisteredtrademarks;andCommunicationsSystemforWindowsNT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBM Corporation.InnoDBisatrademarkofInnobaseOy.ItaniumisaregisteredtrademarkofIntelCorporation.LinuxisaregisteredtrademarkofLinus Torvalds.W3Cisaregisteredtrademark,andXWindowSystemisatrademarkoftheMassachusettsInstituteofTechnology.MetaSolvisaregistered trademarkofMetasolvSoftware,Inc.ActiveX,Microsoft,Outlook,VisualBasic,VisualSourceSafe,Windows,WindowsNT,andWindowsServerare registeredtrademarksofMicrosoftCorporation.SixSigmaisaregisteredtrademarkofMotorola,Inc.FirefoxandMozillaareregisteredtrademarksofthe MozillaFoundation.MySQLisaregisteredtrademarkofMySQLAB.nCipherisatrademarkofnCipherCorporationLtd.EclipseisatrademarkofEclipse Foundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregisteredtrademarkoftheEuropeanUnionandtheUnitedStates.Financial InformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCand TransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PARISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isa registeredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2,Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390, OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,andz/OSareregisteredtrademarks;andCommunicationsSystemforWindows NT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBMCorporation.InnoDBisatrademarkofInnobaseOy.Itaniumisaregistered trademarkofIntelCorporation.TeradataisaregisteredtrademarkofNCRCorporation.NetscapeisaregisteredtrademarkofNetscapeCommunications Corporation.ServletExecisaregisteredtrademark,andNewAtlantaisatrademarkofNewAtlantaCommunications,LLC.SUSEisaregisteredtrademark ofNovell,Inc.AppiaisaregisteredtrademarkandJavelinTechnologiesisatrademarkofNYFIX,Inc.CORBAisaregisteredtrademarkofObject ManagementGroup,Inc.JDEdwards,OneWorld,Oracle,PeopleSoft,Siebel,andVantiveareregisteredtrademarks;andInfranet,PeopleSoftPureInternet Architecture,Portal,andWorldSoftwarearetrademarksofOracleCorporation.PerforceisatrademarkofPerforceSoftware.JBossandRedHatare registeredtrademarksofRedHat,Inc.PIPandRosettaNetaretrademarksofRosettaNet,anonprofitorganization.SAPandR/3areregisteredtrademarks ofSAPAG.PVCSisaregisteredtrademarkofSerenaSoftware,Inc.SWIFTandSWIFTNetareregisteredtrademarksofSocietyforWorldwideInterbank FinancialTelecommunicationSCRL.SPARCandSPARCStationareregisteredtrademarksofSPARCInternational,Inc.BAANandSSAareregistered trademarks;andSSAGlobalisatrademarkofSSAGlobalTechnologies,Inc.EJB,EnterpriseJavaBeans,Java,JavaServer,JDBC,JSP,J2EE,Solaris,Sun,and SunMicrosystemsareregisteredtrademarks;andJavaNamingandDirectoryInterface,JavaServerPages,SOAPwithAttachmentsAPIforJava,andSunSoft aretrademarksofSunMicrosystems,Inc.SybaseisaregisteredtrademarkofSybase,Inc.VERITASisaregisteredtrademark,andVERITASClusterServeris atrademarkofSymantecCorporation.UNIXisaregisteredtrademarkofTheOpenGroup.UnicodeisatrademarkofUnicode,Inc.VeriSignisaregistered trademarkofVerisign,Inc. SoftwareAGandallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG. Otherproductandcompanynamesmentionedhereinmaybethetrademarksoftheirrespectiveowners. Copyright2007webMethods,Inc.Allrightsreserved. Copyright2007SoftwareAGand/oritssuppliers,Uhlandstrasse12,64297Darmstadt,Germany.Allrightsreserved.

Document ID: DEV-PS-DG-71-20070831

Contents

Contents
About this Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 1. An Introduction to the Publish-and-Subscribe Model . . . . . . . . . . . . . . . . . . .


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is the Publish-and-Subscribe Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Elements in the Publish-and-Subscribe Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Triggers (Broker/Local Triggers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Canonical Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11
12 12 13 13 13 14 14 14 15 15 15 16

Chapter 2. An Overview of the Publish and Subscribe Paths . . . . . . . . . . . . . . . . . . . . . .


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of the Publishing Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Documents to the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Documents When the Broker Is Not Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Documents and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of the Subscribe Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Subscribe Path for Published Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Subscribe Path for Delivered Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Local Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
18 18 19 21 23 27 27 30 34

Chapter 3. Steps for Building a Publish-and-Subscribe Solution . . . . . . . . . . . . . . . . . . .


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1: Research the Integration Problem and Determine Solution . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Determine the Production Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3: Create the Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 4: Make the Publishable Document Types Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 5: Create the Services that Publish the Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 6: Create the Services that Process the Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

39
40 41 41 41 42 42 43

Publish-Subscribe Developers Guide Version 7.1

Contents

Step 7: Define the Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Step 8: Synchronize the Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4. Configuring the Integration Server to Publish and Subscribe to Documents


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configure the Connection to the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Document Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a User Account for Invoking Services Specified in Triggers . . . . . . . . . . . . . . . . . . . . . . . Configuring Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Settings for a Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Integration Server for Key Cross-Reference and Echo Suppression . . . . . . . . . . . . . . . . Configuring Integration Server to Handle Native Broker Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47
48 48 49 49 50 53 53 53

Chapter 5. Working with Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . .


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Making an Existing IS Document Type Publishable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Publishable Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . . About the Associated Broker Document Type Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . Setting Publication Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting a Document Storage Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Storage Versus Client Queue Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Time-to-Live for a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Validation for a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Important Considerations when Editing Publishable Document Types . . . . . . . . . . . . . . . . . . . . Renaming a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Making a Publishable Document Type Unpublishable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronization Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronization Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Combining Synchronization Action with Synchronization Status . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing One Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Multiple Document Types Simultaneously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Document Types in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Document Types Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

55
56 56 57 59 62 64 65 66 66 67 68 69 71 71 72 72 73 75 75 76 78 80 81 85 85

Publish-Subscribe Developers Guide Version 7.1

Contents

Importing and Overwriting References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When You Overwrite Elements on the Integration Server? . . . . . . . . . . . . . . . . What Happens if You Do Not Overwrite Elements on the Integration Server? . . . . . . . . . . . . . . Testing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

85 86 86 86

Chapter 6. Publishing Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


The Publishing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Fields in the Document Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Activation ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Publish a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing a Document and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Publish a Request Document and Wait for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delivering a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Deliver a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Failover and Document Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delivering a Document and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Deliver a Document and Wait for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replying to a Published or Delivered Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Envelope of the Received Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Create a Service that Sends a Reply Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

91
92 92 94 94 95 97 98 101 101 103 104 104 107 108 108

Chapter 7. Working with Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Building a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trigger Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Filter for a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filter Evaluation at Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filters and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Filter for a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Conditions in a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Conditions for Ordered Service Execution . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Conditions to a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ordering Conditions in a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Enabling a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling and Enabling Triggers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 114 115 117 117 121 122 122 123 123 124 125 126 126 126 127

Publish-Subscribe Developers Guide Version 7.1

Contents

Setting a Join Time-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join Time-outs for All (AND) Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join Time-outs for Only One (XOR) Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Join Time-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Trigger Queue Capacity and Refill Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Document Acknowledgements for a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting Messaging Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial Processing in Clustered Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Concurrent Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting Document Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Document Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Fatal Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transient Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Retry Behavior for Trigger Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Requirements for Retrying a Trigger Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Retry Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Throw Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Suspend and Retry Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transient Error Handling Properties for a Trigger . . . . . . . . . . . . . . . . . . . . . . Trigger Service Retries and Shutdown Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Triggers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Join Conditions from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

128 128 129 129 130 132 133 133 134 136 137 138 138 140 140 141 141 142 143 144 147 149 149 150 150 152

Chapter 8. Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Document Processing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Redelivery Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When the Document History Database Is Not Available? . . . . . . . . . . . . . Documents without UUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing the Size of the Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Resolver Service and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 154 155 157 159 161 162 162 163 163 164

Publish-Subscribe Developers Guide Version 7.1

Contents

Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

165 166 168 168 169

Chapter 9. Understanding Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribe Path for Documents that Satisfy a Join Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Subscribe Path for Documents that Satisfy an All (AND) Join Condition . . . . . . . . . . . . . . . The Subscribe Path for Documents that Satisfy an Only one (XOR) Join Condition . . . . . . . . . Join Conditions in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 172 173 174 177 181

Chapter 10. Synchronizing Data Between Multiple Resources . . . . . . . . . . . . . . . . . . . . . . 183


Data Synchronization Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Synchronization with webMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Equivalent Data and Native IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Canonical Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Canonical Documents and Canonical IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Cross-Referencing and the Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Cross-Reference Table Is Used for Key Cross-Referencing . . . . . . . . . . . . . . . . . Echo Suppression for N-Way Synchronizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the isLatchedClosed Field Is Used for Echo Suppression . . . . . . . . . . . . . . . . . . . . . Tasks to Perform to Set Up Data Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing the Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining How a Source Resource Sends Notification of a Data Change . . . . . . . . . . . . . . . . . . . . . . When Using an Adapter with the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Developing Your Own Interaction with the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining the Structure of the Canonical Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Key Cross-Referencing in the Source Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . Built-In Services for Key Cross-Referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting up the Source Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Key Cross-Referencing in the Target Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . For N-Way Synchronizations Add Echo Suppression to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-in Services for Echo Suppression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Echo Suppression to Notification Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Incorporating Echo Suppression Logic into a Notification Service . . . . . . . . . . . . . . . . . . . Adding Echo Suppression to Update Trigger Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Incorporating Echo Suppression Logic into an Update Service . . . . . . . . . . . . . . . . . . . . . 184 184 186 187 188 188 189 191 192 196 197 198 198 199 199 200 201 202 205 208 209 209 210 212 213

Publish-Subscribe Developers Guide Version 7.1

Contents

Appendix A. Naming Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217


Naming Rules for webMethods Developer Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Naming Rules for webMethods Broker Document Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Appendix B. Building a Resource Monitoring Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Publish-Subscribe Developers Guide Version 7.1

About this Book

About this Book

webMethodsDeveloperprovidestoolstointegrateresources.Itenablesuserstobuild integrationsolutionslocallywithinonewebMethodsIntegrationServeroracrossmultiple IntegrationServersallexchanginginformationviaaBroker.Thisguideisfordevelopers andadministratorswhowanttomakeuseofthiscapability. Note: WithwebMethodsDeveloper,youcancreateBroker/localtriggersandJMStriggers. ABroker/localtriggeristriggerthatsubscribestoandprocessesdocuments published/deliveredlocallyortotheBroker.AJMStriggerisatriggerthatreceives messagesfromadestination(queueortopic)onaJMSproviderandthenprocessesthose messages.ThisguidediscussesdevelopmentanduseofBroker/localtriggersonly.Where thetermtriggersappearsinthisguide,itreferstoBroker/localtriggers.Forinformation aboutcreatingJMStriggers,seethewebMethodsIntegrationServerJMSClientDevelopers Guide.

Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchange basedonyourspecificsituationorenvironment.Identifiestermsthe firsttimetheyaredefinedintext.Alsoidentifiesserviceinputand outputvariables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously arejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.

Narrow font
Typewriter font

UPPERCASE \ []

Publish-Subscribe Developers Guide Version 7.1

About this Book

Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyou withimportantsourcesofinformationaboutwebMethodsproducts: Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides troubleshootinginformationformanywebMethodsproducts. Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto theDocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe documentationduringproductinstallationtoasingledirectorycalled _documentation,locatedbydefaultunderwebMethodsinstallationdirectory.In addition,youcanfinddocumentationforallwebMethodsproductsonthe webMethodsBookshelf.

Publish-Subscribe Developers Guide Version 7.1

10

Chapter 1. An Introduction to the Publish-and-Subscribe Model

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 What Is the Publish-and-Subscribe Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 webMethods Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Basic Elements in the Publish-and-Subscribe Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Publish-Subscribe Developers Guide Version 7.1

11

1. An Introduction to the Publish-and-Subscribe Model

Introduction
Companiestodayaretaskedwithimplementingsolutionsformanytypesofintegration challengeswithintheenterprise.Manyofthesechallengesrevolvearoundapplication integration(betweensoftwareapplicationsandothersystems)andfallintocommon patterns,suchas Propagation. Propagationofsimilarbusinessobjectsfromonesystemtomultipleother systems,forexample,anorderstatuschangeoraproductpricechange. Synchronization.Synchronizationofsimilarbusinessobjectsbetweentwoormore systemstoobtainasingleview,forexample,realtimesynchronizationofcustomer, productregistration,productorder,andproductSKUinformationamongseveral applications.Thisisthemostcommonissuerequiringanintegrationsolution. Inaonewaysynchronization,thereisonesystem(resource)thatactsasadata sourceandoneormoreresourcesthataretargetsofthesynchronization. Inatwowaysynchronization,everyresourceisbothapotentialsourceandtarget ofasynchronization.Thereisnotasingleresourcethatactsastheprimarydata resource.Achangetoanyresourceshouldbereflectedinallotherresources.This iscalledatwowaysynchronization. Aggregation.Informationjoinedfrommultiplesourcesintoacommondestination system,forexample,communicatingpharmacycustomerrecordsandprescription transactionsandWebsitedataintoacentralapplicationanddatabase. ThewebMethodsproductsuiteprovidestoolsthatyoucanusetodesignanddeploy solutionsthataddressthesechallengesusingapublishandsubscribemodel.

What Is the Publish-and-Subscribe Model?


Thepublishandsubscribemodelisaspecifictypeofmessagebasedsolutioninwhich messagesareexchangedanonymouslythroughamessagebroker.Applicationsthat produceinformationthatneedstobesharedwillmakethisinformationavailablein specifictypesofrecognizabledocumentsthattheypublishtothemessagebroker. Applicationsthatrequireinformationsubscribetothedocumenttypestheyneed. Atruntime,themessagebrokerreceivesdocumentsfrompublishersandthendistributes thedocumentstosubscribers.Thesubscribingapplicationprocessesorperformswork usingthedocumentandmayormaynotsendaresponsetothepublishingapplication. InawebMethodssystem,thewebMethodsIntegrationServerorapplicationsrunningon thewebMethodsIntegrationServerpublishdocumentstotheBroker.TheBrokerthen routesthedocumentstosubscriberslocatedonotherIntegrationServers.Thefollowing sectionsprovidemoredetailaboutthesecomponents.

Publish-Subscribe Developers Guide Version 7.1

12

1. An Introduction to the Publish-and-Subscribe Model

webMethods Components
TheIntegrationServerandtheBrokershareafast,efficientprocessforexchanging documentsacrosstheentirewebMethodssystem.
Resource Integration Server Adapters Resource

Integration Server

Broker

Resources Integration Server Cluster

Integration Server
TheIntegrationServeristhesystemscentralruntimecomponent.Itservesastheentry pointforthesystemsandapplicationsthatyouwanttointegrate,andisthesystems primaryenginefortheexecutionofintegrationlogic.Italsoprovidestheunderlying handlersandfacilitiesthatmanagetheorderlyprocessingofinformationfromresources insideandoutsidetheenterprise.TheIntegrationServerpublishesdocumentstoand receivesdocumentsfromtheBroker.FormoreinformationabouttheIntegrationServer, seethewebMethodsIntegrationServerAdministratorsGuide.

Broker
TheBrokerformsthegloballyscalablemessagingbackboneofwebMethodscomponents. Itprovidestheinfrastructureforimplementingasynchronous,messagebasedsolutions thatarebuiltonthepublishandsubscribemodeloroneofitsvariants,request/replyor publishandwait.

Publish-Subscribe Developers Guide Version 7.1

13

1. An Introduction to the Publish-and-Subscribe Model

TheroleoftheBrokeristoroutedocumentsbetweeninformationproducers(publishers) andinformationconsumers(subscribers).TheBrokerreceives,queues,anddelivers documents. TheBrokermaintainsaregistryofdocumenttypesthatitrecognizes.Italsomaintainsa listofsubscribersthatareinterestedinreceivingthosetypesofdocuments.Whenthe Brokerreceivesapublisheddocument,itqueuesitforthesubscribersofthatdocument type.Subscribersretrievedocumentsfromtheirqueues.Thisactionusuallytriggersan activityonthesubscriberssystemthatprocessesthedocument. AwebMethodssystemcancontainmultipleBrokers.Brokerscanoperateingroups, calledterritories,whichallowseveralBrokerstosharedocumenttypeandsubscription information.ForadditionalinformationaboutBrokers,seethewebMethodsBroker AdministratorsGuide. FormoreinformationabouthowdocumentsflowbetweentheIntegrationServerandthe Broker,seeChapter 2,AnOverviewofthePublishandSubscribePaths.

Basic Elements in the Publish-and-Subscribe Model


Thefollowingsectionsdescribethebasicbuildingblocksofanintegrationsolutionthat usesthepublishandsubscribemodel.

Documents
Inanintegrationsolutionbuiltonthepublishandsubscribemodel,applicationspublish andsubscribetodocuments.DocumentsareobjectsthatwebMethodscomponentsuseto encapsulateandexchangedata.Adocumentrepresentsthebodyofdatathataresource passestowebMethodscomponents.Oftenitrepresentsabusinesseventsuchasplacing anorder(purchaseorderdocument),shippinggoods(shippingnotice),oraddinganew employee(newemployeerecord). Eachpublisheddocumentincludesanenvelope.Theenvelopeismuchlikeaheaderinan emailmessage.Theenveloperecordsinformationsuchasthesendersaddress,thetime thedocumentwassent,sequencenumbers,andotherusefulinformationforroutingand control.Itcontainsinformationaboutthedocumentanditstransitthroughyour webMethodssystem.

Publishable Document Types


Everypublisheddocumentisassociatedwithapublishabledocumenttype.Apublishable documenttypeisanamedschemalikedefinitionthatdescribesthestructureofaparticular kindofdocumentthatcanbepublishedandsubscribedto.Aninstanceofapublishable documenttypecaneitherbepublishedlocallywithinanIntegrationServer,orcanbe publishedtoaBroker.InapublicationenvironmentthatincludesaBroker,each publishabledocumenttypeisboundtoaBrokerdocumenttype.ClientsontheBroker

Publish-Subscribe Developers Guide Version 7.1

14

1. An Introduction to the Publish-and-Subscribe Model

subscribetopublishabledocumenttypes.TheBrokerusespublishabledocumenttypesto determinewhichclientstodistributedocumentsto. Formoreinformationaboutpublishabledocumenttypes,seeChapter 5,Workingwith PublishableDocumentTypes.

Triggers (Broker/Local Triggers)


Trigger,specificallyBroker/localtriggersestablishsubscriptionstopublishabledocument types.Triggersalsospecifytheservicesthatwillprocessdocumentsreceivedbythe subscription.Withinatrigger,aconditionassociatesoneormorepublishabledocument typeswithaservice. Formoreinformationabouttriggers,seeChapter 7,WorkingwithTriggers. Note: WithwebMethodsDeveloper,youcancreateBroker/localtriggersandJMStriggers. ThisguidediscussesdevelopmentanduseofBroker/localtriggersonly.Wheretheterms triggerortriggersappearinthisguide,theyrefertoBroker/localtriggers.

Services
Servicesaremethodlikeunitsofwork.TheycontainlogicthattheIntegrationServer executes.Youbuildservicestocarryoutworksuchasextractingdatafromdocuments, interactingwithbackendresources,andpublishingdocumentstotheBroker.Whenyou buildatrigger,youspecifytheservicethatyouwanttousetoprocessthedocumentsthat yousubscribeto. Formoreinformationaboutbuildingservices,seethewebMethodsDeveloperUsersGuide.

Adapter Notifications
AdapternotificationsnotifyyourwebMethodssystemwheneveraspecificeventoccurson anadaptersresource.Theadapternotificationpublishesadocumentwhenthespecified eventoccursontheresource.Forexample,ifyouareusingtheJDBCAdapteranda changeoccursinadatabasetablethatanadapternotificationismonitoring,theadapter notificationpublishesadocumentcontainingdatafromtheeventandsendsittothe IntegrationServer.Eachadapternotificationhasanassociatedpublishabledocument type.TheIntegrationServerassignsthisdocumenttypethesamenameastheadapter notificationbutappendsPublishDocumenttothename. Youcanusetriggerstosubscribetothepublishabledocumenttypesassociatedwith adapternotifications.Theserviceassociatedwiththepublishabledocumenttypeinthe triggerconditionmightperformsomeadditionalprocessing,updating,or synchronizationbasedonthecontentsoftheadapternotification.

Publish-Subscribe Developers Guide Version 7.1

15

1. An Introduction to the Publish-and-Subscribe Model

Canonical Documents
Acanonicaldocumentisastandardizedrepresentationthatadocumentmightassume whileitispassingthroughyourwebMethodssystem.Acanonicaldocumentactsasthe intermediarydataformatbetweenresources. Forexample,inanimplementationthatacceptspurchaseordersfromcompanies,oneof thestepsintheprocessconvertsthepurchaseorderdocumenttoacompanysstandard purchaseorderformat.Thisformatiscalledthecanonicalformofthepurchaseorder document.Thecanonicaldocumentispublished,delivered,andpassedtoservicesthat processpurchaseorders. Byconvertingadocumenttoaneutralintermediateformat,subscribers(suchasadapter services)onlyneedtoknowhowtoconvertthecanonicaldocumenttotherequired applicationformat.Ifcanonicaldocumentswerenotused,everysubscriberwouldhaveto beabletodecodethenativedocumentformatofeverypublisher. Acanonicaldocumentisapublishabledocumenttype.Thecanonicaldocumentisused whenbuildingpublishingservicesandsubscribedtowhenbuildingtriggers.Inflow services,youcanmapdocumentsfromthenativeformatofanapplicationtothe canonicalformat.

Publish-Subscribe Developers Guide Version 7.1

16

Chapter 2. An Overview of the Publish and Subscribe Paths

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Overview of the Publishing Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Overview of the Subscribe Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Overview of Local Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Publish-Subscribe Developers Guide Version 7.1

17

2. An Overview of the Publish and Subscribe Paths

Introduction
InthewebMethodssystem,IntegrationServersexchangedocumentsviapublicationand subscription.OneIntegrationServerpublishesadocumentandoneormoreIntegration Serverssubscribetoandprocessthatdocument. ThischapterprovidesoverviewsofhowtheIntegrationServerinteractswiththeBroker topublishandsubscribetodocuments,specifically HowtheIntegrationServerpublishesdocumentstotheBroker. HowtheIntegrationServerretrievesdocumentsfromtheBroker. HowtheIntegrationServerpublishesandsubscribestodocumentslocally. Note: Unlessotherwisenoted,thisguidedescribesthefunctionalityandinteractionofthe webMethodsIntegrationServerversion7.1andthewebMethodsBrokerversion7.1.

Overview of the Publishing Path


WhentheIntegrationServerisconfiguredtoconnecttoaBroker,theIntegrationServer canpublishdocumentstotheBroker.TheBrokerthenroutesthedocumentstoallofthe subscribers. ThefollowingsectionsdescribehowtheIntegrationServerinteractswiththeBrokerin thesepublishingscenarios: PublishingadocumenttotheBroker. PublishingadocumenttotheBrokerwhentheBrokerisnotavailable. PublishingadocumenttotheBrokerandwaitingforareply(request/reply). Note: IfaBrokerisnotconfiguredfortheIntegrationServer,allpublishesbecomelocal publishes,anddeliveringdocumentstoaspecificrecipientisnotavailable.Formore informationaboutpublishingdocumentslocally,seeOverviewofLocalPublishingon page 34.

Publish-Subscribe Developers Guide Version 7.1

18

2. An Overview of the Publish and Subscribe Paths

Publishing Documents to the Broker


WhentheIntegrationServersendsdocumentstoaconfiguredBroker,theIntegration Servereitherpublishesordeliversthedocument. WhentheIntegrationServerpublishesadocument,itisbroadcasttoallsubscribers. TheBrokerroutesthedocumenttoallclientssubscribedtothatdocument. WhentheIntegrationServerdeliversadocument,thedeliveryrequestidentifiesthe documentrecipient.TheBrokerplacesthedocumentinthequeueforthespecified clientonly. ThefollowingdiagramillustrateshowtheIntegrationServerpublishesordelivers documentstotheBrokerwhentheBrokerisconnected.
Publishing to the Broker
webMethods Integration Server Publishing Service Dispatcher Connection Pool webMethods Broker

1 7

2 7

3 6 5

Memory

Guaranteed Storage Client Queue X Client Queue Y

Step
1

Description ApublishingserviceontheIntegrationServersendsadocumenttothe dispatcher(oranadapternotificationpublishesadocumentwhenanevent occursontheresourcetheadaptermonitors). BeforetheIntegrationServersendsthedocumenttothedispatcher,itvalidates thedocumentagainstitspublishabledocumenttype.Ifthedocumentisnot valid,theservicereturnsanexceptionspecifyingthevalidationerror.

Thedispatcherobtainsaconnectionfromtheconnectionpool.Theconnection poolisareservedsetofconnectionsthattheIntegrationServerusestopublish documentstotheBroker.TopublishadocumenttotheBroker,theIntegration Serverusesaconnectionforthedefaultclient. ThedispatchersendsthedocumenttotheBroker.

Publish-Subscribe Developers Guide Version 7.1

19

2. An Overview of the Publish and Subscribe Paths

Step
4

Description TheBrokerexaminesthestoragetypeforthedocumenttodeterminehowto storethedocument. Ifthedocumentisvolatile,theBrokerstoresthedocumentinmemory. Ifthedocumentisguaranteed,theBrokerstoresthedocumentinmemory andondisk.

TheBrokerroutesthedocumenttosubscribersbydoingoneofthefollowing: Ifthedocumentwaspublished(broadcast),theBrokeridentifiessubscribers andplacesacopyofthedocumentintheclientqueueforeachsubscriber. Ifthedocumentwasdelivered,theBrokerplacesthedocumentinthe queuefortheclientspecifiedinthedeliveryrequest. Iftherearenosubscribersforthedocument,theBrokerreturnsan acknowledgementtothepublisherandthendiscardsthedocument.If, however,adeadlettersubscriptionexistsforthedocument,theBroker depositsthedocumentinthequeuecontainingthedeadlettersubscription. Formoreinformationaboutcreatingdeadlettersubscriptions,see webMethodsBrokerClientJavaAPIReferenceGuide. AdocumentremainsinthequeueontheBrokeruntilitispickedupbythe subscribingclient.Ifthetimetoliveforthedocumentelapses,theBroker discardsthedocument.Formoreinformationaboutsettingtimetolivefora publishabledocumenttype,seeSettingtheTimetoLiveforaPublishable DocumentTypeonpage 68.

Ifthedocumentisguaranteed,theBrokerreturnsanacknowledgementtothe dispatchertoindicatesuccessfulreceiptandstorageofthedocument.The dispatcherreturnstheconnectiontotheconnectionpool. TheIntegrationServerreturnscontroltothepublishingservice,whichexecutes thenextstep.

Notes: YoucanconfigurepublishabledocumenttypesandIntegrationServersothat IntegrationServerdoesnotvalidatedocumentswhentheyarepublished.Formore informationaboutvalidatingpublishabledocumenttypes,seeSpecifyingValidation foraPublishableDocumentTypeonpage 69. IfatransienterroroccurswhiletheIntegrationServerpublishesadocument,the auditsubsystemlogsthedocumentandassignsitastatusofFAILED.Atransienterror isanerrorthatarisesfromaconditionthatmightberesolvedquickly,suchasthe unavailabilityofaresourceduetonetworkissuesorfailuretoconnecttoadatabase. YoucanusewebMethodsMonitortofindandresubmitdocumentswithastatusof FAILED.

Publish-Subscribe Developers Guide Version 7.1

20

2. An Overview of the Publish and Subscribe Paths

Publishing Documents When the Broker Is Not Available


TheIntegrationServerconstantlymonitorsitsconnectiontotheBrokerandwillalterthe publishingpathifitdeterminesthattheconfiguredBrokerisnotavailable.IftheBrokeris notconnected,theIntegrationServerroutesguaranteeddocumentstoanoutbound documentstore.Thedocumentsremainintheoutbounddocumentstoreuntilthe connectiontotheBrokerisreestablished. ThefollowingdiagramillustrateshowtheIntegrationServerpublishesdocumentswhen theBrokerisdisconnected.
Publishing when the Broker is not available
webMethods Integration Server Publishing Service Dispatcher Connection Pool webMethods Broker

Memory

4 2
Outbound Document Store

Guaranteed Storage Client Queue X Client Queue Y

3 7

Step
1

Description ApublishingserviceontheIntegrationServersendsadocumenttothe dispatcher(oranadapternotificationpublishesadocumentwhenanevent occursontheresourcetheadaptermonitors). BeforetheIntegrationServersendsthedocumenttothedispatcher,itvalidates thedocumentagainstitspublishabledocumenttype.Ifthedocumentisnot valid,theservicereturnsanexceptionspecifyingthevalidationerror.

ThedispatcherdetectsthattheBrokerisnotavailableanddoesoneofthe followingdependingonthestoragetypeofthedocument: Ifthedocumentisguaranteed,thedispatcherroutesthedocumenttothe outbounddocumentstoreondisk. Ifthedocumentisvolatile,thedispatcherdiscardsthedocumentandthe publishingservicethrowsanexception. TheIntegrationServerexecutesthenextstepinthepublishingservice.

Publish-Subscribe Developers Guide Version 7.1

21

2. An Overview of the Publish and Subscribe Paths

Step
3 4

Description WhentheIntegrationServerreestablishesaconnectiontotheBroker,the IntegrationServerobtainsasingleconnectionfromtheconnectionpool TheIntegrationServerautomaticallysendsthedocumentsfromtheoutbound documentstoretotheBroker.Toemptytheoutbounddocumentstoremore rapidly,theIntegrationServersendsthedocumentsinbatchesinsteadofone atatime. Note: TheIntegrationServerusesasingleconnectiontoemptytheoutbound documentstoretopreservepublicationorder.

5 6

TheBrokerexaminesthestoragetypeforthedocument,determinesthatitis guaranteedandstoresthedocumentinmemoryandondisk. TheBrokerroutesthedocumenttosubscribersbydoingoneofthefollowing: Ifthedocumentwaspublished(broadcast),theBrokeridentifies subscribersandplacesacopyofthedocumentintheclientqueueforeach subscriber. Ifthedocumentwasdelivered,theBrokerplacesthedocumentinthe queuefortheclientspecifiedinthedeliveryrequest. Iftherearenosubscribersforthedocument,theBrokerreturnsan acknowledgementtothepublisherandthendiscardsthedocument.If, however,adeadlettersubscriptionexistsforthedocument,theBroker depositsthedocumentinthequeuecontainingthedeadlettersubscription. Formoreinformationaboutcreatingdeadlettersubscriptions,see webMethodsBrokerClientJavaAPIReferenceGuide. AdocumentremainsinthequeueontheBrokeruntilthesubscribingclient picksitup.Ifthetimetoliveforthedocumentelapses,theBrokerdiscardsthe document.Formoreinformationaboutsettingtimetoliveforapublishable documenttype,seeSettingtheTimetoLiveforaPublishableDocument Typeonpage 68.

TheBrokerreturnsanacknowledgementtotheIntegrationServertoindicate successfulreceiptandstorageoftheguaranteeddocument.TheIntegration Serverremovesthedocumentfromtheoutbounddocumentstore.

Publish-Subscribe Developers Guide Version 7.1

22

2. An Overview of the Publish and Subscribe Paths

Notes: Ifyoudonotwantpublisheddocumentsplacedintheoutbounddocumentstore whentheBrokerisunavailable,youcanconfigureIntegrationServertothrowa ServiceExceptioninstead.Thevalueofthewatt.server.publish.useCSQparameter determineswhetherIntegrationServerplacesdocumentsintheoutbounddocument storeorthrowsaServiceException. AftertheconnectiontotheBrokerisreestablished,theIntegrationServersendsall newlypublisheddocuments(guaranteedandvolatile)totheoutbounddocument storeuntiltheoutboundstorehasbeenemptied.ThisallowstheIntegrationServerto maintainpublicationorder.AftertheIntegrationServeremptiestheoutbound documentstore,theIntegrationServerresumespublishingdocumentsdirectlytothe Broker. IfIntegrationServermakes4attemptstotransmitadocumentfromtheoutbound documentstoretotheBrokerandallattemptsfail,theauditsubsystemlogsthe documentandassignsitastatusofSTATUS_TOO_MANY_TRIES. IfatransienterroroccurswhiletheIntegrationServerpublishesadocument,the auditsubsystemlogsthedocumentandassignsitastatusofFAILED. YoucanconfigurepublishabledocumenttypesandIntegrationServersothat IntegrationServerdoesnotvalidatedocumentswhentheyarepublished.Formore informationaboutvalidatingpublishabledocumenttypes,seeSpecifyingValidation foraPublishableDocumentTypeonpage 69. Tip! YoucanusewebMethodsMonitortofindandresubmitdocumentswithastatusof STATUS_TOO_MANY_TRIESorFAILED.Formoreinformationaboutusing webMethodsMonitor,seethewebMethodsMonitordocumentation.

Publishing Documents and Waiting for a Reply


Inapublishandwaitscenario,aservicepublishesadocument(arequest)andthenwaits forareplydocument.Thisissometimescalledtherequest/replymodel.Arequest/reply canbesynchronousorasynchronous. Inasynchronousrequest/reply,thepublishingflowservicestopsexecutingwhileit waitsforaresponse.Whentheservicereceivesareplydocumentfromthespecified client,theserviceresumesexecution Inanasynchronousrequest/reply,thepublishingflowservicecontinuesexecutingafter publishingtherequestdocument.Thatis,thepublishingservicedoesnotwaitfora replybeforeexecutingthenextstepintheflowservice.Thepublishingflowservice mustinvokeaseparateservicetoretrievethereplydocument.

Publish-Subscribe Developers Guide Version 7.1

23

2. An Overview of the Publish and Subscribe Paths

ThefollowingdiagramillustrateshowtheIntegrationServerandBrokerhandlea synchronousrequest/reply.
Publishing a document to the Broker and waiting for a reply
webMethods Integration Server Publishing Service Dispatcher Connection Pool webMethods Broker

Memory

4 6
Pending Replies

Guaranteed Storage Client Queue X Client Queue Y

5 10

11

Publishing Servers Request/Reply Client Queue

Step
1

Description Apublishingservicesendsadocument(therequest)tothedispatcher.The IntegrationServerpopulatesthetagfieldinthedocumentenvelopewitha uniqueidentifierthatwillbeusedtomatchupthereplydocumentwiththis request. Thepublishingserviceentersintoawaitingstate.Theservicewillnotresume executionuntilitreceivesareplyfromasubscriberorthewaittime elapses.TheIntegrationServerbeginstrackingthewaittimeassoonasit publishesthedocument. BeforetheIntegrationServersendsthedocumenttothedispatcher,itvalidates thedocumentagainstitspublishabledocumenttype.Ifthedocumentisnot valid,theservicereturnsanexceptionspecifyingthevalidationerror.The serviceunblocks,butwithanexception.

Publish-Subscribe Developers Guide Version 7.1

24

2. An Overview of the Publish and Subscribe Paths

Step
2

Description Thedispatcherobtainsaconnectionfromtheconnectionpool.Theconnection poolisareservedsetofconnectionsthattheIntegrationServerusestopublish documentstotheBroker.TopublisharequestdocumenttotheBroker,the IntegrationServerusesaconnectionfortherequest/replyclient. Note: IftheBrokerisnotavailable,thedispatcherroutesthedocumenttothe outbounddocumentstore.Formoreinformation,seePublishingDocuments WhentheBrokerIsNotAvailableonpage 21.

3 4

ThedispatchersendsthedocumenttotheBroker. TheBrokerexaminesthestoragetypeforthedocumenttodeterminehowto storethedocument. Ifthedocumentisvolatile,theBrokerstoresthedocumentinmemory. Ifthedocumentisguaranteed,theBrokerstoresthedocumentinmemory andondisk.

TheBrokerroutesthedocumenttosubscribersbydoingoneofthefollowing: Ifthedocumentwaspublished(broadcast),theBrokeridentifies subscribersandplacesacopyofthedocumentintheclientqueueforeach subscriber. Ifthedocumentwasdelivered,theBrokerplacesthedocumentinthe queuefortheclientspecifiedinthedeliveryrequest. Iftherearenosubscribersforthedocument,theBrokerreturnsan acknowledgementtothepublisherandthendiscardsthedocument.If, however,adeadlettersubscriptionexistsforthedocument,theBroker depositsthedocumentinthequeuecontainingthedeadlettersubscription. Formoreinformationaboutcreatingdeadlettersubscriptions,see webMethodsBrokerClientJavaAPIReferenceGuide. AdocumentremainsinthequeueontheBrokeruntilitispickedupbythe subscribingclient.Ifthetimetoliveforthedocumentelapses,theBroker discardsthedocument.Formoreinformationaboutsettingtimetolivefora publishabledocumenttype,seeSettingtheTimetoLiveforaPublishable DocumentTypeonpage 68.

Ifthedocumentisguaranteed,theBrokerreturnsanacknowledgementtothe dispatchertoindicatesuccessfulreceiptandstorageofthedocument.The dispatcherreturnstheconnectiontotheconnectionpool.

Publish-Subscribe Developers Guide Version 7.1

25

2. An Overview of the Publish and Subscribe Paths

Step
7

Description Subscribersretrieveandprocessthedocument. Asubscriberusesthepub.publish:replyservicetocomposeandpublishareply document.Thisserviceautomaticallypopulatesthetagfieldofthereply documentenvelopewiththesamevalueusedinthetagfieldoftherequest documentenvelope. Thepub.publish:replyservicealsoautomaticallyspecifiestherequestingclientas therecipientofthereplydocument

OneormoresubscriberssendreplydocumentstotheBroker.TheBroker storesthereplydocumentsinmemory. TheBrokerplacesthereplydocumentsintherequest/replyclientqueueforthe IntegrationServerthatinitiatedtherequest.

9 10 11

TheIntegrationServerthatinitiatedtherequestobtainsarequest/replyclient fromtheconnectionpoolandretrievesthereplydocumentsfromtheBroker. TheIntegrationServerusesthetagvalueofthereplydocumenttomatchup thereplywiththeoriginalrequest. TheIntegrationServerplacesthereplydocumentinthepipelineofthewaiting service.Thewaitingserviceresumesexecution.

Notes: Iftherequestingservicespecifiedapublishabledocumenttypeforthereply document,thereplydocumentmustconformtothespecifiedtype.Otherwise,the replydocumentcanbeaninstanceofanypublishabledocumenttype. Asinglerequestmightreceivemanyreplies.TheIntegrationServerthatinitiatedthe requestusesonlythefirstreplydocumentitretrievesfromtheBroker.The IntegrationServerdiscardsallotherreplies.Firstisarbitrarilydefined.Thereisno guaranteeprovidedfortheorderinwhichtheBrokerprocessesincomingreplies. Allreplydocumentsaretreatedasvolatiledocuments.Volatiledocumentsarestored inmemoryandwillbelostifresourceonwhichthereplydocumentislocatedshuts downorifaconnectionislostwhilethereplydocumentisintransit. Ifthewaittimeelapsesbeforetheservicereceivesareply,theIntegrationServerends therequest,andtheservicereturnsanulldocumentthatindicatestherequesttimed out.TheIntegrationServerthenexecutesthenextstepintheflowservice.Ifareply documentarrivesaftertheflowserviceresumesexecution,theIntegrationServer rejectsthedocumentandcreatesajournallogmessagestatingthatthedocumentwas rejectedbecausethereisnothreadwaitingforthedocument. YoucanconfigurepublishabledocumenttypesandIntegrationServersothat IntegrationServerdoesnotvalidatedocumentswhentheyarepublished.Formore

Publish-Subscribe Developers Guide Version 7.1

26

2. An Overview of the Publish and Subscribe Paths

informationaboutvalidatingpublishabledocumenttypes,seeSpecifyingValidation foraPublishableDocumentTypeonpage 69.

Overview of the Subscribe Path


WhenIntegrationServerisconnectedtoaBroker,thepathadocumentfollowsonthe subscribersideincludesretrievingthedocumentfromtheBroker,storingthedocument onIntegrationServer,andprocessingthedocument.Thesubscriptionpathfora documentdependsonwhetherthedocumentwaspublishedtoallsubscribers(broadcast) ordeliveredtoIntegrationServerdirectly. ThefollowingsectionsdescribehowIntegrationServerinteractswiththeBrokerto retrievepublishedanddelivereddocuments. Note: Forinformationaboutthesubscribepathfordocumentsthatmatchajoincondition, seeSubscribePathforDocumentsthatSatisfyaJoinConditiononpage 173.

The Subscribe Path for Published Documents


Whenadocumentispublishedorbroadcast,theBrokerplacesacopyofthedocumentin theclientqueueforeachsubscribingtrigger.Eachsubscribingtriggerwillretrieveand processthedocument. Thefollowingdiagramillustratesthepathofadocumenttoasubscriber(trigger)onthe IntegrationServer.

Publish-Subscribe Developers Guide Version 7.1

27

2. An Overview of the Publish and Subscribe Paths

Subscribe path for published documents


webMethods Broker webMethods Integration Server

1
Client Queue X Client Queue Y

Dispatcher

3
Memory Trigger Document Store

Guaranteed Storage

Trigger Queue X

Trigger Queue Y

4
Trigger Service X1 Trigger Service X2 Trigger Service Y1 Trigger Service Y2

6 5

Step
1

Description ThedispatcherontheIntegrationServerusesaserverthreadtorequest documentsfromatriggersclientqueueontheBroker. Note: EachtriggerontheIntegrationServerhasacorrespondingclientqueue ontheBroker.

2 3

Thethreadretrievesabatchofdocumentsforthetrigger. Thedispatcherplacesthedocumentsinthetriggersqueueinthetrigger documentstore.Thetriggerdocumentstoreissavedinmemory.The dispatcherthenreleasestheserverthreadusedtoretrievethedocuments.

Publish-Subscribe Developers Guide Version 7.1

28

2. An Overview of the Publish and Subscribe Paths

Step
4

Description Thedispatcherobtainsathreadfromtheserverthreadpool,pullsadocument fromthetriggerqueue,andevaluatesthedocumentagainsttheconditionsin thetrigger. Note: Ifexactlyonceprocessingisconfiguredforthetrigger,theIntegration Serverfirstdetermineswhetherthedocumentisaduplicateofonethathas alreadybeenprocessedbythetrigger.TheIntegrationServercontinues processingthedocumentonlyifthedocumentisnew.

Ifthedocumentmatchesatriggercondition,thedispatcherexecutesthe triggerserviceassociatedwiththatcondition. Ifthedocumentdoesnotmatchatriggercondition,theIntegrationServer discardsthedocument,returnsanacknowledgementtotheBroker,and returnstheserverthreadtotheserverthreadpool.TheIntegrationServeralso generatesajournallogmessagestatingthatthedocumentdidnotmatcha condition.

Afterthetriggerserviceexecutestocompletion(successorerror),oneofthe followingoccurs: Ifthetriggerserviceexecutedsuccessfully,theIntegrationServerreturns anacknowledgementtotheBroker(ifthisisaguaranteeddocument).The IntegrationServerthenremovesthecopyofthedocumentfromthetrigger queueandreturnstheserverthreadtothethreadpool. Ifaserviceexceptionoccurs,thetriggerserviceendsinerrorandthe IntegrationServerrejectsthedocument.Ifthedocumentisguaranteed,the IntegrationServerreturnsanacknowledgementtotheBroker.The IntegrationServerremovesthecopyofthedocumentfromthetrigger queue,returnstheserverthreadtothethreadpool,andsendsanerror documenttoindicatethatanerrorhasoccurred. Ifatransienterroroccursduringtriggerserviceexecutionandtheservice catchestheerror,wrapsitandrethrowsitasanISRuntimeException,then theIntegrationServerwaitsforthelengthoftheretryintervalandre executestheserviceusingtheoriginaldocumentasinput.Ifthe IntegrationServerreachesthemaximumnumberofretriesandthetrigger servicestillfailsbecauseofatransienterror,theIntegrationServertreats thelastfailureasaserviceerror.Formoreinformationaboutretryinga triggerservice,seeConfiguringTransientErrorHandlingonpage 140.

Publish-Subscribe Developers Guide Version 7.1

29

2. An Overview of the Publish and Subscribe Paths

Notes: Afterreceivinganacknowledgement,theBrokerremovesitscopyofthedocument fromguaranteedstorage.TheIntegrationServerreturnsanacknowledgementfor guaranteeddocumentsonly. IftheIntegrationServershutsdownorreconnectstotheBrokerbefore acknowledgingaguaranteeddocument,theIntegrationServerrecoversthe documentfromtheBrokerwhentheserverrestartsortheconnectionis reestablished.(Thatis,thedocumentsareredelivered.)Formoreinformationabout guaranteeddocuments,seeSelectingaDocumentStorageTypeonpage 66. Ifatriggerservicegeneratesauditdataonerrorandincludesacopyoftheinput pipelineintheauditlog,youcanusewebMethodsMonitortoreinvokethetrigger serviceatalatertime.Formoreinformationaboutconfiguringservicestogenerate auditdata,seethewebMethodsDeveloperUsersGuide. Itispossiblethatadocumentcouldsatisfymorethanoneconditioninatrigger. However,theIntegrationServerexecutesonlytheserviceassociatedwiththefirst satisfiedcondition. TheprocessingmodeforatriggerdetermineswhethertheIntegrationServer processesdocumentsinatriggerqueueseriallyorconcurrently.Inserialprocessing, theIntegrationServerprocessesthedocumentsoneatatimeintheorderinwhichthe documentswereplacedinthetriggerqueue.Inconcurrentprocessing,theIntegration Serverprocessesasmanydocumentsasitcanatonetime,butnotnecessarilyinthe sameorderinwhichthedocumentswereplacedinthequeue.Formoreinformation aboutdocumentprocessing,seeSelectingMessagingProcessingonpage 133. Ifatransienterroroccursduringdocumentretrievalorstorage,theauditsubsystem logsthedocumentandassignsitastatusofFAILED.Atransienterrorisanerrorthat arisesfromaconditionthatmightberesolvedlater,suchastheunavailabilityofa resourceduetonetworkissuesorfailuretoconnecttoadatabase.Youcanuse webMethodsMonitortofindandresubmitdocumentswithaFAILEDstatus.For moreinformationaboutusingwebMethodsMonitor,seethewebMethodsMonitor documentation. Youcanconfigureatriggertosuspendandretryatalatertimeifretryfailureoccurs. RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Formore informationabouthandlingretryfailure,seeHandlingRetryFailureonpage 141.

The Subscribe Path for Delivered Documents


Apublishingservicecandeliveradocumentbyspecifyingthedestinationofthe document.Thatis,thepublishingservicespecifiestheBrokerclientthatistoreceivethe document.WhentheBrokerreceivesadelivereddocument,itplacesacopyofthe documentinthequeueforthespecifiedclientonly.

Publish-Subscribe Developers Guide Version 7.1

30

2. An Overview of the Publish and Subscribe Paths

Typically,documentsaredeliveredtothedefaultclient.ThedefaultclientistheBroker clientcreatedfortheIntegrationServerwhentheIntegrationServerfirstconfiguresits connectiontotheBroker. Note: Ifapublishingservicespecifiesanindividualtriggerasthedestinationofthe document(thepublishingservicespecifiesatriggerclientIDasthedestinationID),the subscribepaththedocumentfollowsisthesameasthepathfollowedbyapublished document. Thefollowingdiagramillustratesthesubscriptionpathforadocumentdeliveredtothe defaultclient.
Subscribe path for documents delivered to the default client
webMethods Broker Client Queue Default Client webMethods Integration Server

1 2
Dispatcher

Memory

Default Document Store

5 4
Trigger Document Store

Guaranteed Storage

Trigger Queue X

Trigger Queue Y

6 8 7
Trigger Service X1 Trigger Service X2 Trigger Service Y1 Trigger Service Y2

6 8 7

Publish-Subscribe Developers Guide Version 7.1

31

2. An Overview of the Publish and Subscribe Paths

Step
1

Description ThedispatcherontheIntegrationServerrequestsdocumentsfromthedefault clientsqueueontheBroker. Note: ThedefaultclientistheBrokerclientcreatedfortheIntegrationServer. TheBrokerplacesdocumentsinthedefaultclientsBrokerqueueonlyifthe publisherdeliveredthedocumenttotheIntegrationServersclientID.

Thethreadretrievesdocumentsdeliveredtothedefaultclientinbatches. Thenumberofdocumentsthethreadretrievesatonetimeisdeterminedbythe capacityandrefilllevelofthedefaultdocumentstoreandthenumberof documentsavailableforthedefaultclientontheBroker.Formoreinformation aboutconfiguringthedefaultdocumentstore,seethewebMethodsIntegration ServerAdministratorsGuide.

3 4

Thedispatcherplacesacopyofthedocumentsinmemoryinthedefault documentstore. Thedispatcheridentifiessubscriberstothedocumentandroutesacopyofthe documenttoeachsubscriberstriggerqueue. Inthecaseofdelivereddocuments,theIntegrationServersavesthedocuments toatriggerqueue.Thetriggerqueueislocatedwithinatriggerdocumentstore thatissavedondisk.

TheIntegrationServerremovesthecopyofthedocumentfromthedefault documentstoreand,ifthedocumentisguaranteed,returnsan acknowledgementtotheBroker.TheBrokerremovesthedocumentfromthe defaultclientsqueue. Thedispatcherobtainsathreadfromtheserverthreadpool,pullsthe documentfromthetriggerqueue,andevaluatesthedocumentagainstthe conditionsinthetrigger. Note: Ifexactlyonceprocessingisconfiguredforthetrigger,theIntegration Serverfirstdetermineswhetherthedocumentisaduplicateofonealready processedbythetrigger.TheIntegrationServercontinuesprocessingthe documentonlyifthedocumentisnew.

Publish-Subscribe Developers Guide Version 7.1

32

2. An Overview of the Publish and Subscribe Paths

Step
7

Description Ifthedocumentmatchesatriggercondition,theIntegrationServerexecutes thetriggerserviceassociatedwiththatcondition. Ifthedocumentdoesnotmatchatriggercondition,theIntegrationServer, sendsanacknowledgementtothetriggerqueue,discardsthedocument (removesitfromthetriggerqueue),andreturnstheserverthreadtotheserver threadpool.TheIntegrationServeralsogeneratesajournallogmessagestating thatthedocumentdidnotmatchacondition.

Afterthetriggerserviceexecutestocompletion(successorerror),oneofthe followingoccurs: Ifthetriggerserviceexecutedsuccessfully,theIntegrationServerreturns anacknowledgementtothetriggerqueue(ifthisisaguaranteed document),removesthedocumentfromthetriggerqueue,andreturnsthe serverthreadtothethreadpool. Ifaserviceexceptionoccurs,thetriggerserviceendsinerrorandthe IntegrationServerrejectsthedocument,removesthedocumentfromthe triggerqueue,returnstheserverthreadtothethreadpool,andsendsan errordocumenttoindicatethatanerrorhasoccurred.Ifthedocumentis guaranteed,theIntegrationServerreturnsanacknowledgementtothe triggerqueue.Thetriggerqueueremovesitscopyoftheguaranteed documentfromstorage. Ifatransienterroroccursduringtriggerserviceexecutionandtheservice catchestheerror,wrapsitandrethrowsitasanISRuntimeException,then theIntegrationServerwaitsforthelengthoftheretryintervalandre executestheserviceusingtheoriginaldocumentasinput.IftheIntegration Serverreachesthemaximumnumberofretriesandthetriggerservicestill failsbecauseofatransienterror,theIntegrationServertreatsthelast failureasaserviceerror.Formoreinformationaboutretryingatrigger service,seeConfiguringTransientErrorHandlingonpage 140.

Notes: TheIntegrationServersavesdelivereddocumentsinatriggerdocumentstorelocated ondisk.TheIntegrationServersavespublisheddocumentsinatriggerdocument storelocatedinmemory. IftheIntegrationServershutsdownbeforeprocessingaguaranteeddocumentsaved inatriggerdocumentstoreondisk,theIntegrationServerrecoversthedocument fromthetriggerdocumentstorewhenitrestarts.Volatiledocumentsaresavedin memoryandarenotrecovereduprestart. Ifaservicegeneratesauditdataonerrorandincludesacopyoftheinputpipelinein theauditlog,youcanusewebMethodsMonitortoreinvokethetriggerserviceata

Publish-Subscribe Developers Guide Version 7.1

33

2. An Overview of the Publish and Subscribe Paths

latertime.Formoreinformationaboutconfiguringservicestogenerateauditdata,see thewebMethodsDeveloperUsersGuide. Itispossiblethatadocumentcouldmatchmorethanoneconditioninatrigger. However,theIntegrationServerexecutesonlytheserviceassociatedwiththefirst matchedcondition. TheprocessingmodeforatriggerdetermineswhethertheIntegrationServer processesdocumentsinatriggerqueueseriallyorconcurrently.Inserialprocessing, theIntegrationServerprocessesthedocumentsoneatatimeintheorderinwhichthe documentswereplacedinthetriggerqueue.Inconcurrentprocessing,theIntegration Serverprocessesasmanydocumentsasitcanatonetime,butnotnecessarilyinthe sameorderinwhichthedocumentswereplacedinthequeue.Formoreinformation aboutdocumentprocessing,seeSelectingMessagingProcessingonpage 133. Ifatransienterroroccursduringdocumentretrievalorstorage,theauditsubsystem logsthedocumentandassignsitastatusofFAILED.YoucanusewebMethods MonitortofindandresubmitdocumentswithaFAILEDstatus.Formoreinformation aboutusingwebMethodsMonitor,seethewebMethodsMonitordocumentation. Youcanconfigureatriggertosuspendandretryatalatertimeifretryfailureoccurs. RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Formore informationabouthandlingretryfailure,seeHandlingRetryFailureonpage 141.

Overview of Local Publishing


LocalpublishingreferstotheprocessofpublishingadocumentwithintheIntegration Server.OnlysubscriberslocatedonthesameIntegrationServercanreceiveandprocess thedocument.Inlocalpublishing,thedocumentremainswithintheIntegrationServer. ThereisnoBrokerinvolvement. Localpublishingoccurswhentheservicethatpublishesthedocumentspecifiesthatthe documentshouldbepublishedlocallyorwhentheIntegrationServerisnotconfiguredto connecttoaBroker.

Publish-Subscribe Developers Guide Version 7.1

34

2. An Overview of the Publish and Subscribe Paths

Thefollowingdiagramillustrateshowthepublishandsubscribepathsforalocally publisheddocument.
Publishing a document locally
webMethods Integration Server

Publishing Service

Dispatcher

2
Trigger Document Store

Trigger Queue X

Trigger Queue Y

Trigger Queue Z

3 5 4
Trigger Service X1 Trigger Service X2 Trigger Service Y1 Trigger Service Y2 Trigger Service Z1 Trigger Service Z2

3 5 4

Step
1

Description ApublishingserviceontheIntegrationServersendsadocumenttothe dispatcher. BeforetheIntegrationServersendsthedocumenttothedispatcher,itvalidates thedocumentagainstitspublishabledocumenttype.Ifthedocumentisnot valid,theservicereturnsanexceptionspecifyingthevalidationerror.

Thedispatcherdoesoneofthefollowing: Thedispatcherdetermineswhichtriggerssubscribetothedocumentand placesacopyofthedocumentineachsubscriberstriggerqueue.The dispatchersaveslocallypublisheddocumentsinatriggerdocumentstore locatedondisk. Iftherearenosubscribersforthedocument,thedispatcherdiscardsthe document.

Publish-Subscribe Developers Guide Version 7.1

35

2. An Overview of the Publish and Subscribe Paths

Step
3

Description Thedispatcherobtainsathreadfromtheserverthreadpool,pullsthe documentfromthetriggerqueue,andevaluatesthedocumentagainstthe conditionsinthetrigger. Note: Ifexactlyonceprocessingisconfiguredforthetrigger,theIntegration Serverfirstdetermineswhetherthedocumentisaduplicateofonealready processedbythetrigger.TheIntegrationServercontinuesprocessingthe documentonlyifthedocumentisnew.

Ifthedocumentmatchesatriggercondition,thedispatcherexecutesthetrigger serviceassociatedwiththatcondition. Ifthedocumentdoesnotmatchatriggercondition,theIntegrationServer sendsanacknowledgementtothetriggerqueue,discardsthedocument (removesitfromthetriggerqueue),andreturnstheserverthreadtotheserver threadpool.

Afterthetriggerserviceexecutestocompletion(successorerror),oneofthe followingoccurs: Ifthetriggerserviceexecutedsuccessfully,theIntegrationServersendsan acknowledgementtothetriggerqueue(ifthisisaguaranteeddocument), removesthedocumentfromthetriggerqueue,andreturnstheserver threadtothethreadpool. Ifaserviceexceptionoccurs,thetriggerserviceendsinerrorandthe IntegrationServerrejectsthedocument,removesthedocumentfromthe triggerqueue,andreturnstheserverthreadtothethreadpool.Ifthe documentisguaranteed,theIntegrationServersendsan acknowledgementtothetriggerqueue. Ifatransienterroroccursduringtriggerserviceexecutionandtheservice catchestheerror,wrapsitandrethrowsitasanISRuntimeException,then theIntegrationServerwaitsforthelengthoftheretryintervaland reexecutestheserviceusingtheoriginaldocumentasinput.IfIntegration Serverreachesthemaximumnumberofretriesandthetriggerservicestill failsbecauseofatransienterror,theIntegrationServertreatsthelast failureasaserviceerror.Formoreinformationaboutretryingatrigger service,seeConfiguringTransientErrorHandlingonpage 140.

Publish-Subscribe Developers Guide Version 7.1

36

2. An Overview of the Publish and Subscribe Paths

Notes: YoucanconfigurepublishabledocumenttypesandIntegrationServersothat IntegrationServerdoesnotvalidatedocumentswhentheyarepublished.Formore informationaboutvalidatingpublishabledocumenttypes,seeSpecifyingValidation foraPublishableDocumentTypeonpage 69. IntegrationServersaveslocallypublisheddocumentsinatriggerdocumentstore locatedondisk.IfIntegrationServershutsdownbeforeprocessingalocally publishedguaranteeddocument,IntegrationServerrecoversthedocumentfromthe triggerdocumentstorewhenitrestarts.IntegrationServerdoesnotrecovervolatile documentswhenitrestarts. Ifasubscribingtriggerqueuereachesitsmaximumcapacity,youcanconfigure IntegrationServertorejectlocallypublisheddocumentsforthattriggerqueue.For moreinformationaboutthisfeature,seethedescriptionofthe watt.server.publish.local.rejectOOSparameterinthewebMethodsIntegrationServer AdministratorsGuide. Ifaservicegeneratesauditdataonerrorandincludesacopyoftheinputpipelinein theauditlog,youcanusewebMethodsMonitortoreinvokethetriggerserviceata latertime.Formoreinformationaboutconfiguringservicestogenerateauditdata,see thewebMethodsDeveloperUsersGuide. Itispossiblethatadocumentcouldmatchmorethanoneconditioninatrigger. However,IntegrationServerexecutesonlytheserviceassociatedwiththefirst matchedcondition. TheprocessingmodeforatriggerdetermineswhethertheIntegrationServer processesdocumentsinatriggerqueueseriallyorconcurrently.Inserialprocessing, IntegrationServerprocessesthedocumentsoneatatimeintheorderinwhichthe documentswereplacedinthetriggerqueue.Inconcurrentprocessing,theIntegration Serverprocessesasmanydocumentsasitcanatonetime,butnotnecessarilyinthe sameorderinwhichthedocumentswereplacedinthequeue.Formoreinformation aboutdocumentprocessing,seeSelectingMessagingProcessingonpage 133. Youcanconfigureatriggertosuspendandretryatalatertimeifretryfailureoccurs. RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Formore informationabouthandlingretryfailure,seeHandlingRetryFailureonpage 141. YoucanconfigureIntegrationServertostrictlyenforcealocallypublished documentstimetoliveanddiscardthedocumentbeforeprocessingitifthe documenthasexpired.Formoreinformationaboutthisfeature,seethedescriptionof thewatt.server.trigger.local.checkTTLparameterinthewebMethodsIntegrationServer AdministratorsGuide.

Publish-Subscribe Developers Guide Version 7.1

37

2. An Overview of the Publish and Subscribe Paths

Publish-Subscribe Developers Guide Version 7.1

38

Chapter 3. Steps for Building a Publish-and-Subscribe Solution

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Step 1: Research the Integration Problem and Determine Solution . . . . . . . . . . . . . . . . . . . . . . 41 Step 2: Determine the Production Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Step 3: Create the Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Step 4: Make the Publishable Document Types Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Step 5: Create the Services that Publish the Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Step 6: Create the Services that Process the Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Step 7: Define the Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Step 8: Synchronize the Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Publish-Subscribe Developers Guide Version 7.1

39

3. Steps for Building a Publish-and-Subscribe Solution

Introduction
Therearetwosidesofapublishandsubscribemodelintegrationsolution.Onesideisthe publishingsideandtheotheristhesubscribingside.Thetablebelowlistswhatyoumust createforeachsideoftheintegrationsolution. On the publishing side, create: Publishabledocumenttypesforthe documentsthataretobepublished Servicesthatpublishthe documents On the subscribing side, create: Servicestoprocesstheincoming documentsthatarepublishedbythe publishingside Triggersthatassociatestheincoming documentswithservicesthat processesthedocuments

Thefollowingtableliststhetasksthatyouneedtoperformtobuildanintegration solutionandwhetherthepublishingsideorthesubscribingsideisresponsibleforthe task. Step


1 2 3 4 5 6 7

Task Researchtheintegrationproblemand determinehowyouwanttoresolveit. Determinethedevelopmentenvironment. Createthepublishabledocumenttypesforthe documentstobepublished. Makethepublishabledocumenttypes availabletothesubscribingside. Createtheservicesthatpublishthe documents. Createtheservicesthatprocessthepublished documents. Definethetriggersthatassociatethepublished documentstotheservicesthatprocessesthe document. Synchronizethepublishabledocumenttypesif necessary.

Publishing

Subscribing

Publish-Subscribe Developers Guide Version 7.1

40

3. Steps for Building a Publish-and-Subscribe Solution

Step 1: Research the Integration Problem and Determine Solution


Thefirststeptobuildinganintegrationsolutionistodefinetheproblemanddetermine howtosolvetheproblemusingthepublishandsubscribemodel.Whendesigningthe solution,determine: Documents that you are going to need to publish/subscribe.Youwillusethisinformation whencreatingthepublishabledocumenttypes. How you need to publish the documents. Youwillusethisinformationwhencreatingthe servicesthatpublishthedocuments. How you need to process the documents.Youwillusethisinformationwhencreatingthe servicesthatprocessthedocuments.

Step 2: Determine the Production Configuration


Determinewhatyourproductionconfigurationwillbelike.Youmightwantyour developmentenvironmenttomirroryourproductionenvironment.Questionstoanswer are: Willallthedocumentpublishingandsubscribingbeperformedonasingle IntegrationServerorwillyouusemultipleIntegrationServers? IfyouusemultipleIntegrationServers,willyouconfigureacluster? WillyouuseaBrokerintheproductionenvironment?

Step 3: Create the Publishable Document Type


Afteryoudeterminethedocumentsthatyouaregoingtopublishinyoursolution,onthe publishingside,usethewebMethodsDevelopertocreatethepublishabledocument types.Formoreinformationabouthowtocreatepublishabledocumenttypes,see Chapter 5,WorkingwithPublishableDocumentTypes.

Publish-Subscribe Developers Guide Version 7.1

41

3. Steps for Building a Publish-and-Subscribe Solution

Step 4: Make the Publishable Document Types Available


Tocreateservicesthatprocessdocumentsandtriggersthatsubscribetodocuments,the subscribingsideneedsthepublishabledocumenttypesthatdefinethedocumentsthat willbepublished.Thefollowingtabledescribeshowtomakethepublishabledocument typesavailablebasedonyourdevelopmentenvironment. Development Environment One Integration Server. Publishingside andsubscribingsidearebeing developedononesingleIntegration Server. Action to Take Youdonothavetotakeanyactionstomakethe publishabledocumenttypesavailabletoother developers.Afteryoucreatethepublishable documenttypeforthepublishingside,the publishabledocumenttypeisimmediately availableforthesubscribingsidetouse. Whenyoucreatethepublishabledocument type,acorrespondingBrokerdocumenttypeis automaticallycreatedontheBroker.Youcan makepublishabledocumenttypesavailableto otherdevelopersoneofthefollowingways: UseDevelopertocreateapublishable documenttypefromtheBrokerdocument type.Forinstructionsforhowtocreatea publishabledocumenttypefromaBroker documenttype,seeCreatingaPublishable DocumentTypefromaBrokerDocument Typeonpage 59. OR Usepackagereplicationtodistribute publishabledocumenttypestodevelopers workingwithotherIntegrationServers. Whenotherdevelopersreceivethepackage, theyshouldinstallthepackageandthenuse Developertosynchronizethedocument typesbypullingthemfromtheBroker.

Multiple Integration Servers with a Broker. Publishingsideand subscribingsideareeachbeing developedonseparateIntegration ServersconnectedbyaBroker.

Step 5: Create the Services that Publish the Documents


Onthepublishingside,youneedtocreatetheservicesthatwillpublishthedocumentsto theBrokerorlocallyonthesameIntegrationServer.UseDeveloperoryourown developmentenvironmenttocreatetheseservices.Formoreinformationabouthowto createapublishingservice,seeChapter 6,PublishingDocuments.

Publish-Subscribe Developers Guide Version 7.1

42

3. Steps for Building a Publish-and-Subscribe Solution

Step 6: Create the Services that Process the Documents


Onthesubscribingside,youneedtocreatetheservicesthatwillprocesstheincoming documents.UseDeveloperoryourowndevelopmentenvironmenttocreatethese services.Whencreatingaservicetoprocessadocument,includeintheinputsignaturea documentreferencetothepublishabledocumenttypeforthepublisheddocument.Inthis way,youcanreferencethedatainthedocumentusingthefieldsdefinedinthe publishabledocumenttype. Formoreinformationaboutrequirementsforservicesthatprocesspublisheddocuments, seeServiceRequirementsonpage 115.Formoreinformationaboutcreatingservices andusingdocumentreferencesininputsignatures,seethewebMethodsDeveloperUsers Guide.

Step 7: Define the Triggers


Onthesubscribingside,createtriggerstoassociateoneormorepublishabledocument typeswiththeservicethatprocessesthepublisheddocuments.Toassociateapublishable documenttypewiththeservice,youcreateaconditioninthetriggerthatidentifiesthe publishabledocumenttypeyouaresubscribingtoandtheservicetoinvokewhena documentofthattypearrives.Youcanfurtherrefinetheconditionbyaddingfiltersthat specifiescriteriaforthecontentsofapublisheddocument.Whenyousavethetrigger,the IntegrationServerusestheconditionsinthetriggertodefinesubscriptionstopublishable documenttypes. Formoreinformationabouthowtodefinetriggers,seeChapter 7,Workingwith Triggers.

Step 8: Synchronize the Publishable Document Types


WhenaBrokerisincludedinyourintegrationsolution,eachpublishabledocumenttype musthaveacorrespondingBrokerdocumenttypeontheBroker.Inapublishand subscribeintegrationsolution,boththepublishingsideandthesubscribingsideusethe samepublishabledocumenttype.Thepublishingsideusesthepublishabledocument typewhenpublishingthedocumenttotheBrokertoidentifythetypeofdocumentbeing published.Thesubscribingsidereferencesthepublishabledocumenttypeinthetriggerto indicatethetypeofdocumentbeingsubscribedto.Fortheintegrationsolutiontowork

Publish-Subscribe Developers Guide Version 7.1

43

3. Steps for Building a Publish-and-Subscribe Solution

correctly,thepublishabledocumenttypeonthepublishingsideandthesubscribingside mustreferencethesameBrokerdocumenttype.
Publishable document types must be associated with the same Broker document type

Publishing Side
Integration Server publishable document type document Broker Broker document type

Subscribing Side
Integration Server publishable document type trigger

Thefollowingtabledescribeshowtomakeyourpublishabledocumenttypecorrespond tothesameBrokerdocumenttypebasedonyourdevelopmentenvironment. Development Environment One Integration Server. Publishingsideand subscribingsideare beingdevelopedon onesingleIntegration Server. Action to Take Whenyoumoveyourintegrationsolutionintoproduction, thepublishingsideandsubscribingsidemightbeon differentIntegrationServersthatareconnectedbyaBroker. YouwillneedtosynchronizetocreatetheBrokerdocument typesassociatedwiththepublishabledocumenttypes. Formoreinformationsynchronizingdocumenttypes,see SynchronizingPublishableDocumentTypesonpage 75. Action on publishing side: Duringsynchronization,pushthepublishabledocument typetotheBrokertocreatetheBrokerdocumenttypeonthe Broker.Usepackagereplicationtocreateanddistribute packagescontainingthepublishabledocumenttypes. Action on subscribing side: Installthepackagecontainingpublishabledocumenttypes createdbythepublisher.Duringsynchronization,pull documenttypesfromtheBrokertoupdatethepublishable documenttypes.

Publish-Subscribe Developers Guide Version 7.1

44

3. Steps for Building a Publish-and-Subscribe Solution

Development Environment Multiple Integration Servers with a Broker. Publishingsideand subscribingsideare eachbeingdeveloped onseparateIntegration Serversconnectedbya Broker.

Action to Take BecauseyouusedtheBrokerduringdevelopment,the publishabledocumenttypesonboththepublishingsideand subscribingsideshouldalreadycorrespondtothesame Brokerdocumenttypes.YoucanusetheSyncAllDocument Typesdialogboxtomakesurethatthepublishable documenttypesaresynchronizedwithBrokerdocument types.Formoreinformationaboutsynchronizingdocument types,seeSynchronizingPublishableDocumentTypeson page 75.

Publish-Subscribe Developers Guide Version 7.1

45

3. Steps for Building a Publish-and-Subscribe Solution

Publish-Subscribe Developers Guide Version 7.1

46

Chapter 4. Configuring the Integration Server to Publish and Subscribe to Documents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Configure the Connection to the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Configuring Document Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Specifying a User Account for Invoking Services Specified in Triggers . . . . . . . . . . . . . . . . . . . 49 Configuring Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Configuring Settings for a Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Configuring Integration Server for Key Cross-Reference and Echo Suppression . . . . . . . . . . . . 53 Configuring Integration Server to Handle Native Broker Events . . . . . . . . . . . . . . . . . . . . . . . . . 53

Publish-Subscribe Developers Guide Version 7.1

47

4. Configuring the Integration Server to Publish and Subscribe to Documents

Introduction
Beforeyoucanbegintopublishandsubscribetodocuments,whetherlocallyorusinga Broker,youneedtospecifysettingsforsomeoftheIntegrationServercomponentsand services.SpecifyingsettingsconsistsofusingtheIntegrationServerAdministratorto: ConfiguretheconnectiontotheBroker(ifpublishingorsubscribingtodocumentson theBroker). ConfigurethedocumentstoreswheretheIntegrationServerwillsavedocuments untiltheycanbepublishedorprocessed. Specifyauseraccountforexecutingservicesspecifiedintriggers. Configureadocumenthistorydatabase. Configureakeycrossreferencingandechosuppressiondatabase. ConfiguresettingsforhandlingnativeBrokerevents. ConfigureotherIntegrationServerparametersthatcanaffectapublishandsubscribe solution. Note: WiththeexceptionofconfiguringtheconnectiontotheBroker,youdonothaveto configurethesesettingsuntilyouhavefinisheddevelopinganintegrationsolutionand arereadytotestthepublication/subscriptionofadocument.

Configure the Connection to the Broker


IfyouwanttousetheBrokerasthemessagingfacilityfordistributingdocumentsyou needtoconfiguretheIntegrationServersconnectiontotheBroker.Althoughyoudonot needtoconnecttheBrokertotheIntegrationServerduringdevelopment,youmustdoso beforeyoucanpublishorsubscribetodocumentsacrosstheenterprise.Ifyoudonot configureaconnectiontotheBroker,theIntegrationServerpublishesalldocuments locally. FordetailedinformationaboutconfiguringaconnectiontotheBroker,seeConfiguring theServerinthewebMethodsIntegrationServerAdministratorsGuide.Formore informationabouttheBroker,seethewebMethodsBrokerAdministratorsGuide. Note: IfyouswitchyourIntegrationServerconnectionfromoneBrokertoaBrokerin anotherterritory,youmayneedtosynchronizeyourpublishabledocumenttypeswith thenewBroker.SwitchingyourBrokerconnectionisnotrecommendedorsupported.For moreinformationaboutsynchronizingpublishabledocumenttypes,seeSynchronizing PublishableDocumentTypesonpage 75.

Publish-Subscribe Developers Guide Version 7.1

48

4. Configuring the Integration Server to Publish and Subscribe to Documents

Configuring Document Stores


TheIntegrationServerusesdocumentstorestosavepublisheddocumentstodiskorto memorywhilethedocumentsareintransitorwaitingtobeprocessed.TheIntegration Servermaintainsthreedocumentstoresforpublisheddocuments. Default document store.Thedefaultdocumentstorecontainsdocumentsdeliveredto theclientIDoftheIntegrationServer.WhentheIntegrationServerretrieves documentsdeliveredtoitsclientID,theserverplacesthedocumentsinthedefault documentstore.Documentsremaininthedefaultdocumentstoreuntilthedispatcher determineswhichtriggerssubscribetothedocument.Thedispatcherthenmovesthe documentstothetriggerqueuesforthesubscribingtriggers. Trigger document store.Thetriggerdocumentstorecontainsdocumentswaitingtobe processedbytriggers.Theserverassignseachtriggeraqueueinthetriggerdocument store.Adocumentremainsinthetriggerqueueuntiltheserversuccessfullyprocesses thedocument. TheIntegrationServersavesmostdocumentsitretrievesfromtheBrokerinatrigger documentstorelocatedinmemory.However,theIntegrationServersavesdocuments deliveredtothedefaultclientinatriggerdocumentstorelocatedondisk.The IntegrationServeralsosaveslocallypublisheddocumentsinatriggerdocumentstore locatedondisk. Outbound document store.Theoutbounddocumentstorecontainsdocumentswaitingto besenttotheBroker.TheIntegrationServerplacesdocumentsintheoutbound documentstorewhentheconfiguredBrokerisnotavailable.Whentheconnectionto theBrokerisrestored,theserveremptiestheoutbounddocumentstorebysending thesaveddocumentstotheBroker. UsingtheIntegrationServerAdministrator,youcanconfigurepropertiesforeach documentstore.Forexample,youcandeterminethestorelocationsandtheinitialstore sizes.

Specifying a User Account for Invoking Services Specified in Triggers


WhenaclientinvokesaserviceviaanHTTPrequest,theIntegrationServerchecksthe credentialsandusergroupmembershipoftheclientagainsttheExecuteACLassignedto theservice.TheIntegrationServerperformsthischecktomakesuretheclientisallowed toinvokethatservice.Inapublishandsubscribesituation,however,theIntegration Serverinvokestheservicewhenitreceivesadocumentratherthanasaresultofaclient request.BecausetheIntegrationServerdoesnotassociateusercredentialswitha publisheddocument,youcanspecifytheuseraccountfortheIntegrationServertouse wheninvokingservicesassociatedwithtriggers.

Publish-Subscribe Developers Guide Version 7.1

49

4. Configuring the Integration Server to Publish and Subscribe to Documents

YoucaninstructtheIntegrationServertoinvokeaserviceusingthecredentialsofoneof thepredefineduseraccounts(Administrator,Central,Default,Developer,Replicator). Youcanalsospecifyauseraccountthatyouoranotherserveradministratordefined. WhentheIntegrationServerreceivesadocumentthatsatisfiesatriggercondition,the IntegrationServerusesthecredentialsforthespecifieduseraccounttoinvoketheservice specifiedinthetriggercondition. Makesurethattheuseraccountyouselectincludesthecredentialsrequiredbythe executeACLsassignedtotheservicesassociatedwithtriggers.Forexample,supposethat youspecifyDeveloperastheuseraccountforinvokingservicesintriggers.The receiveCustomerInfotriggercontainsaconditionthatassociatesapublishabledocumenttype withtheserviceaddCustomer.TheaddCustomerservicespecifiesReplicatorfortheExecute ACL.Whenthetriggerconditionismet,theaddCustomerservicewillnotexecutebecause theusersettingyouselected(Developer)doesnothavethenecessarycredentialsto invoketheservice(Replicator). FormoreinformationaboutsettingtheRun Trigger Service As Userproperty,seethe webMethodsIntegrationServerAdministratorsGuide.

Configuring Server Parameters


IntegrationServerhasserverparametersthatyoucanconfigure.Manyparametersareset asyouadministerIntegrationServerusingtheIntegrationServerAdministrator.The serverparametersthatcanaffectapublishandsubscribesolutionaredescribedbelow. Formoreinformationabouttheseandotherserverparameters,seethewebMethods IntegrationServerAdministratorsGuide. watt.server.broker.producer.multiclient Specifiesthenumberofsessionsforthedefaultclient.ThedefaultclientistheBroker clientthattheIntegrationServerusestopublishdocumentstotheBrokerandtoretrieve documentsdeliveredtothedefaultclient. watt.server.broker.replyConsumer.fetchSize SpecifiesthenumberorreplydocumentsthatIntegrationServerretrievesfromtheBroker atonetime. watt.server.broker.replyConsumer.multiclient Specifiesthenumberofsessionsfortherequest/replyclient.Therequest/replyclientisthe BrokerclientthatIntegrationServerusestosendrequestdocumentstotheBrokerandto retrievereplydocumentsfromtheBroker. watt.server.broker.replyConsumer.sweeperInterval Specifieshowoften(inmilliseconds)IntegrationServersweepsitsinternalmailboxto removeexpiredrepliestopublishedrequests. watt.server.brokerTransport.dur SpecifiesthenumberofsecondsofidletimethattheBrokerwaitsbeforesendingakeep alivemessagetoIntegrationServer.

Publish-Subscribe Developers Guide Version 7.1

50

4. Configuring the Integration Server to Publish and Subscribe to Documents

watt.server.brokerTransport.max SpecifiesthenumberofsecondsthattheBrokerwaitsfortheIntegrationServerto respondtoakeepalivemessage. watt.server.brokerTransport.ret SpecifiesthenumberoftimestheBrokerresendskeepalivemessagesbefore disconnectinganunresponsiveIntegrationServer. watt.server.cluster.aliasList SpecifiesacommadelimitedlistofaliasesforremoteIntegrationServersinacluster. IntegrationServerusesthislistwhenexecutingtheremoteinvokesthatupdatetheother clusternodeswithtriggermanagementchanges(suchassuspending/resumingdocument retrievalordocumentprocessing). watt.server.control.controlledDeliverToTriggers.pctMaxThreshold SpecifiesthetriggerqueuethresholdatwhichIntegrationServerslowsdownthedelivery rateoflocallypublisheddocuments.Thisthresholdisexpressedasapercentageofthe triggerqueuecapacity. watt.server.control.maxPersist Specifiesthecapacityoftheoutbounddocumentstore. watt.server.control.maxPublishOnSuccess Specifiesthemaximumnumberofdocumentsthattheservercanpublishonsuccessat onetime. watt.server.dispatcher.comms.brokerPing Specifieshowoften(inmilliseconds)triggerBrokerClientsshouldpingtheBrokerto preventconnectionsbetweenatriggerBrokerClientandtheBrokerfrombecomingidle, andasaresult,preventthefirewallfromclosingtheidleconnection. watt.server.dispatcher.join.reaperDelay Specifieshowoften(inmilliseconds)thattheIntegrationServerremovesstate informationforcompletedandexpiredjoins.Thedefaultis1800000milliseconds(30 minutes). watt.server.idr.reaperInterval Specifiestheinitialintervalatwhichthescheduledservice wm.server.dispatcher:deleteExpiredUUID executesandremovesexpireddocumenthistory entries. watt.server.publish.local.rejectOOS SpecifieswhetherIntegrationServershouldrejectdocumentspublishedlocally,usingthe pub.publish:publishorpub.publish.publishAndWaitservices,whenthequeueforthesubscribing triggerisatmaximumcapacity.Thedefaultisfalse. Note: Multipletriggerscansubscribetothesamedocument.IntegrationServerplacesthe documentinanysubscribingtriggerqueuethatisnotatcapacity.

Publish-Subscribe Developers Guide Version 7.1

51

4. Configuring the Integration Server to Publish and Subscribe to Documents

watt.server.publish.useCSQ SpecifieswhetherIntegrationServerusesoutboundclientsidequeuingifdocumentsare publishedwhentheBrokerisunavailable.Whenthisparameterissettofalseandthe publishfails,aserviceexceptionoccurs. watt.server.publish.usePipelineBrokerEvent SpecifieswhetherIntegrationServershouldbypassencodingthatisnormallyperformed whendocumentsarepublishedtotheBroker.Formoreinformationaboutwhentoset thisproperty,seeConfiguringIntegrationServertoHandleNativeBrokerEventson page 53. watt.server.publish.validateOnIS SpecifieswhetherIntegrationServervalidatespublisheddocumentsallthetime,never,or onaperdocumenttypebasis.Formoreinformationaboutdocumentvalidation,see SpecifyingValidationforaPublishableDocumentTypeonpage 69. watt.server.trigger.interruptRetryOnShutdown SpecifieswhetherornotarequesttoshutdowntheIntegrationServerinterruptstheretry processforatriggerservice.Thedefaultisfalse.Formoreinformationabout interruptingtriggerserviceretries,seeTriggerServiceRetriesandShutdownRequests onpage 147. watt.server.trigger.keepAsBrokerEvent SpecifieswhetherIntegrationServershouldbypassdecodingthatisnormallyperformed whendocumentsareretrievedfromtheBrokeronbehalfofatrigger.Formore informationaboutwhentosetthisproperty,seeConfiguringIntegrationServerto HandleNativeBrokerEventsonpage 53. watt.server.trigger.local.checkTTL SpecifieswhetherIntegrationServershouldstrictlyenforcealocallypublished documentstimetolive.Whenthisparameterissettotrue,beforeprocessingalocally publisheddocumentinatriggerqueue,IntegrationServerdetermineswhetherthe documenthasexpired.IntegrationServerdiscardsthedocumentifithasexpired.The defaultisfalse. watt.server.trigger.managementUI.excludeList Specifiesacommadelimitedlistoftriggerstoexcludefromthe Trigger Managementpages intheIntegrationServerAdministrator.TheIntegrationServeralsoexcludesthese triggersfromtriggermanagementchangesthatsuspendorresumedocumentretrievalor documentprocessingforalltriggers.TheIntegrationServerdoesnotexcludethese triggersfromchangestocapacity,refilllevel,ormaximumexecutionthreadsthatare madeusingtheglobaltriggercontrols(QueueCapacityThrottleandTriggerExecution ThreadsThrottle). watt.server.trigger.monitoringInterval Specifiestheinterval,measuredinseconds,atwhichIntegrationServerexecutesresource monitoringservices.Aresourcemonitoringserviceisaservicethatyoucreatetocheck theavailabilityofresourcesusedbyatriggerservice.Formoreinformationabout resourcemonitoringservices,seeAppendix B,BuildingaResourceMonitoringService.

Publish-Subscribe Developers Guide Version 7.1

52

4. Configuring the Integration Server to Publish and Subscribe to Documents

watt.server.trigger.preprocess.suspendAndRetryOnError IndicateswhetherIntegrationServersuspendsatriggerifanerroroccursduringthepre processingphaseoftriggerexecution.Thepreprocessingphaseencompassesthetime fromwhenthetriggerretrievesthedocumentfromitslocalqueuetothetimethetrigger serviceexecutes.Formoreinformationaboutthisproperty,seeWhatHappensWhenthe DocumentHistoryDatabaseIsNotAvailable?onpage 161andDocumentResolver ServiceandExceptionsonpage 163. watt.server.trigger.removeSubscriptionOnReloadOrReinstall SpecifieswhetherIntegrationServerdeletesdocumenttypesubscriptionsfortriggers whenthepackagecontainingthetriggerreloadsoranupdateofthepackageisinstalled. watt.server.xref.type Specifieswherekeycrossreferencingandechosuppressioninformationiswritten.

Configuring Settings for a Document History Database


Aspartofprovidingexactlyonceprocessingforatrigger,youcanuseadocumenthistory databasetomaintainarecordofallthedocumentsprocessedbyatrigger.Ifyouwantto usedocumenthistorytoensureexactlyonceprocessingforsomeorallofyourtriggers, youortheserveradministratormustcreatetheDocumentHistorydatabasecomponent andconnectittoaJDBCconnectionpool.Forinstructions,seethewebMethodsInstallation Guide.

Configuring Integration Server for Key Cross-Reference and Echo Suppression


Ifyouintendtousethekeycrossreferencingandechosuppressionservicestoperform datasynchronizations,youmuststorethecrossreferencekeysandthelatchingstatus informationinadatabase.Todoso,youmustcreatetheCrossReferencedatabase componentandconnectittoaJDBCconnectionpool.Forinstructions,seethewebMethods InstallationGuide.

Configuring Integration Server to Handle Native Broker Events


Bydefault,IntegrationServerencodesanddecodesdataitpassestoandfromtheBroker asfollows: WhenIntegrationServersendsadocumenttotheBroker,itfirstencodesthe document(IDataobject)intoaBrokerevent. WhenIntegrationServerreceivesadocumentfromtheBroker,itdecodestheBroker eventintoanIDataobject.

Publish-Subscribe Developers Guide Version 7.1

53

4. Configuring the Integration Server to Publish and Subscribe to Documents

Insomesituations,youmaywanttobypassthisencodingordecodingsteponIntegration ServerandinsteadsendandreceivenativeBrokereventstoandfromtheBroker.These situationsarewhenyou: MigrateEnterprisebusinesslogictoIntegrationServer. UsecustomBrokerclientswritteninJava,C,orCOM/ActiveX. YouconfigureIntegrationServertohandlenativeBrokereventsbysettingserver parameters. To configure Integration Server to handle native Broker events 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickExtended. Lookforthewatt.server.publish.usePipelineBrokerEvent propertyandchangeitsvalueto true. Ifthewatt.server.publish.usePipelineBrokerEventpropertyisnotdisplayed,seethe webMethodsIntegrationServerAdministratorsGuideforinstructionsondisplaying extendedsettings. 4 5 6 7 Lookforthewatt.server.publish.validateOnIS propertyandchangeitsvaluetonever. IfIntegrationServerisretrievingdocumentsfromtheBrokeronbehalfofatrigger, lookforthewatt.server.trigger.keepAsBrokerEvent propertyandchangeitsvaluetotrue. ClickSave Changes. RestartIntegrationServer. Note: Ifyousetthewatt.server.trigger.keepAsBrokerEventpropertytotrueandthe watt.server.publish.validateOnISpropertytoalwaysorperDoc,youwillreceive validationerrors.

Publish-Subscribe Developers Guide Version 7.1

54

Chapter 5. Working with Publishable Document Types

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Creating Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Setting Publication Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Deleting Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Synchronizing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Importing and Overwriting References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Testing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Publish-Subscribe Developers Guide Version 7.1

55

5. Working with Publishable Document Types

Introduction
Apublishabledocumenttypeisanamedschemalikedefinitionthatdescribesthe structureandpublicationpropertiesofaparticularkindofdocument.Essentially,a publishabledocumenttypeisanISdocumenttypewithspecifiedpublicationproperties suchasstoragetypeandtimetolive. Inanintegrationsolutionthatusesthepublishandsubscribemodel,servicespublish instancesofpublishabledocumenttypes,andtriggerssubscribetopublishabledocument types.AtriggerspecifiesaservicethattheIntegrationServerinvokestoprocessthe document.Forexample,youmightcreateapublishabledocumenttypenamedEmpRec thatdescribesthelayoutofanemployeerecord.Youmightcreateatriggerthatspecifies thattheIntegrationServershouldinvoketheaddEmployeeRecordservicewheninstancesof theEmpRecarereceived.Whenaserviceoradapternotificationpublishesadocumentof typeEmpRec,thatdocumentwouldbequeuedforthesubscribersofdocumenttype EmpRec.TheIntegrationServerwouldpassthedocumenttoandinvokethe addEmployeeRecordservice. InapublicationenvironmentthatincludesaBroker,eachpublishabledocumenttypeis associatedwithaBrokerdocumenttype.Developerprovidestoolsthatyoucanuseto ensurethatthesetwodocumenttypesremainsynchronized. Whenyoubuildanintegrationsolutionthatusespublicationandsubscription,youneed tocreatethepublishabledocumenttypesbeforeyoucreatetriggers,servicesthatprocess documents,andservicesthatpublishdocuments.

Creating Publishable Document Types


Oneofthefirststepsinbuildinganintegrationsolutionthatusesthepublishand subscribemodelistocreateanddefinepublishabledocumenttypes.Onceyoucreate publishabledocumenttypes,youorotherdeveloperscansubscribetothosepublishable documenttypesbycreatingtriggers. Tip! Youcandistributethepublishabledocumenttypesthatyoucreatetootherdevelopers throughpackagereplication.Formoreinformation,seeStep4:MakethePublishable DocumentTypesAvailableonpage 42andtheManagingPackagesinthewebMethods IntegrationServerAdministratorsGuide. Youcancreatepublishabledocumenttypesbydoingthefollowing: MakinganexistingISdocumenttypepublishable.Forinformationaboutcreatingan ISdocumenttype,seethewebMethodsDeveloperUsersGuide. CreatinganewdocumenttypebasedonanexistingBrokerdocumenttype Thefollowingsectionsprovidemoreinformationaboutcreatingpublishabledocument types.

Publish-Subscribe Developers Guide Version 7.1

56

5. Working with Publishable Document Types

Making an Existing IS Document Type Publishable


YoucanmakeanexistingISdocumenttypepublishablebysettingpublicationproperties forthedocumenttype.Propertiesthatyoucansetinclude:specifyingwhetherinstances ofthepublishabledocumenttypeshouldbesavedinmemory(volatilestorage)orsaved ondisk(guaranteedstorage)duringprocessing,andspecifyinghowlonginstancesofthe publishabledocumenttypeshouldremainontheBrokeroncetheyarepublished. IftheIntegrationServeronwhichyouhaveasessionisconnectedtoaBroker,whenyou makeanISdocumenttypepublishable,theIntegrationServerautomaticallycreatesa Brokerdocumenttype.TheIntegrationServerautomaticallyassignstheBrokerdocument typeaname.Thisnamecorrespondstothefollowingformat: wm::is::folderName::documentTypeName.Ifadocumenttypewiththisnamealreadyexistson theBroker,theIntegrationServerappends_1totheBrokerdocumenttypename. Forexample,ifyoumaketheISdocumenttypeemployee.employeeInfopublishable,the IntegrationServercreatestheBrokerdocumenttypewm::is::employee::employeeInfo. However,ifadeveloperusinganotherIntegrationServercreatedaBrokerdocumenttype foranidenticallynamedISdocumenttype,theIntegrationServerassignsthenewBroker documenttypethenamewm::is::employee::employeeInfo_1. IftheIntegrationServeronwhichyouhaveasessionisnotconnectedtoaBroker,the publishabledocumenttypesthatyoucreatecanbeusedonlyinlocalpublishes.Thatis, instancesofthepublishabledocumenttypescanonlybepublishedandsubscribedtowith inthesameIntegrationServer.(LocalpublishesdonotinvolveaBroker.)Later,whenthe IntegrationServerisconnectedtoaBroker,youcancreateaBrokerdocumenttypeforthe publishabledocumenttypebypushingthedocumenttypetotheBrokerduring synchronization. Important! IfyouwanttogenerateanassociatedBrokerdocumenttypeatthesametime youmaketheISdocumenttypepublishable,makesurethataBrokerisconfiguredand theIntegrationServeronwhichyouareworkingisconnectedtoit.Formoreinformation aboutconfiguringaconnectionbetweentheIntegrationServerandtheBroker,see ConfiguringtheServerinthewebMethodsIntegrationServerAdministratorsGuide. Note: YoucanonlymakeanISdocumenttypepublishableifyouownthelockontheIS documenttypeandyouhavewritepermissiontotheISdocumenttype.Forinformation aboutlockingelementsandaccesspermissions(ACLs),seethewebMethodsDeveloper UsersGuide.

To make an existing IS document type publishable 1 2 IntheNavigationpanelofDeveloper,opentheISdocumenttypethatyouwantto makepublishable. InthePropertiespanel,underPublication,setthePublishablepropertytoTrue.

Publish-Subscribe Developers Guide Version 7.1

57

5. Working with Publishable Document Types

NexttotheStorage typeproperty,selectthestoragemethodtouseforinstancesofthis publishabledocumenttype. Select... Volatile Guaranteed To... Specifythatinstancesofthispublishabledocumenttypeare volatile.Volatiledocumentsarestoredinmemory. Specifythatinstancesofthispublishabledocumenttypeare guaranteed.Guaranteeddocumentsarestoredondisk.

Formoreinformationaboutselectingastoragetype,seeSelectingaDocument StorageTypeonpage 66. Important! FordocumentspublishedtotheBroker,thestoragetypeassignedtoa documentcanbeoverriddenbythestoragetypeassignedtotheclientqueueonthe Broker.Formoreinformation,seeDocumentStorageVersusClientQueueStorage onpage 67. 4 NexttotheDiscardproperty,selectoneofthefollowingtoindicatehowlonginstances ofthispublishabledocumenttyperemaininthetriggerclientqueuebeforetheBroker discardsthem. Select... False True To... SpecifythattheBrokershouldneverdiscardinstancesofthis publishabledocumenttype. SpecifythattheBrokershoulddiscardinstancesofthis publishabledocumenttypeafterthespecifiedtimeelapses. InthefieldsnexttoTime to livespecifythetimetolivevalue andtimeunits. 5 OntheFilemenu,clickSavetosaveyourchanges.Developerdisplays besidethe documenttypenameintheNavigationpaneltoindicateitisapublishabledocument type.

Notes: Inthe Propertiespanel,theBroker doc type propertydisplaysthenameofthe correspondingdocumenttypecreatedontheBroker.Or,ifyouarenotconnectedtoa Broker,thisfielddisplaysPublishableLocallyOnly.(Later,whentheIntegration ServerisconnectedtoaBroker,youcancreateaBrokerdocumenttypeforthis publishabledocumenttypebypushingthedocumenttypetotheBrokerduring synchronization.)Youcannoteditthecontentsofthisproperty.Formoreinformation aboutthecontentsofthisproperty,seeAbouttheAssociatedBrokerDocumentType Nameonpage 62.

Publish-Subscribe Developers Guide Version 7.1

58

5. Working with Publishable Document Types

Whenyoumakeadocumenttypepublishable,theIntegrationServeraddsan envelopefield(_env)tothedocumenttypeautomatically.Whenadocumentis published,theIntegrationServerandtheBrokerpopulatethisfieldwithmetadata aboutthedocument.Formoreinformationaboutthisfield,seeAbouttheEnvelope Fieldonpage 64. OnceapublishabledocumenttypecorrespondstoanassociatedBrokerdocument type,youneedtomakesurethatthedocumenttypesremaininsync.Thatis,changes inonedocumenttypemustbemadetotheassociateddocumenttype.Youcanupdate onedocumenttypewithchangesintheotherbysynchronizingthem.Forinformation aboutsynchronizingdocumenttypes,seeSynchronizingPublishableDocument Typesonpage 75. Important! TheBrokerprohibitstheuseofcertainfieldnames,forexample,Javakeywords, @,*,andnamescontainingwhitespacesorpunctuation.Ifyoumakeadocumenttype publishableanditcontainsafieldnamethatisnotvalidontheBroker,youcannotaccess andviewthefieldviaanyBrokertool.However,theBrokertransportsthecontentsofthe field,whichmeansthatanyotherIntegrationServerconnectedtothatBrokerhasaccess tothefieldasitwasdisplayedandimplementedontheoriginalIntegrationServer.Use fieldnamesthatareacceptabletotheBroker.SeethewebMethodsBrokerAdministrators GuideforinformationonnamingconventionsforBrokerelements.

Creating a Publishable Document Type from a Broker Document Type


IftheIntegrationServertowhichyouareconnectedisconnectedtoaBroker,youcan createpublishabledocumenttypesfromexistingBrokerdocumenttypes.Theresulting publishabledocumenttypewillhavethesamepublicationpropertiesastheBroker documenttype. WhenyoucreateapublishabledocumenttypefromaBrokerdocumenttypethat referencesotherelements,Developerwillalsocreateanelementforeachreferenced element.TheIntegrationServerwillcontainadocumenttypethatcorrespondstothe BrokerdocumenttypeandonenewelementforeachelementtheBrokerdocumenttype references.Developeralsocreatesthefolderinwhichthereferencedelementwaslocated. Developersavesthenewelementsinthepackageyouselectedforstoringthenew publishabledocumenttype. Forexample,supposethattheBrokerdocumenttypereferencesadocumenttypenamed addressinthecustomerInfofolder.DeveloperwouldcreateanISdocumenttypenamed addressandsaveitinthecustomerInfofolder.IfafieldintheBrokerdocumenttypewas constrainedbyasimpletypedefinitiondeclaredintheISschemapurchaseOrder,Developer wouldcreatethereferencedISschemapurchaseOrder. AnelementreferencedbyaBrokerdocumenttypemighthavethesamenameasan existingelementonyourIntegrationServer.However,elementnamesmustbeuniqueon

Publish-Subscribe Developers Guide Version 7.1

59

5. Working with Publishable Document Types

theIntegrationServer.Developergivesyoutheoptionofoverwritingtheexisting elementswiththereferencedelements.Formoreinformationaboutoverwritingexisting elements,seeImportingandOverwritingReferencesonpage 85. Important! IfyoudonotselecttheOverwrite existing elements when importing referenced elementscheckboxandtheBrokerdocumenttypereferencesanelementwiththesame nameasanexistingIntegrationServerelement,Developerwillnotcreatethepublishable documenttype. Important! Ifyouchoosetooverwriteexistingelementswithnewelements,keepinmind thatdependentsoftheoverwrittenelementswillbeaffected.Forexample,supposethe addressdocumenttypedefinedtheinputsignatureofaflowservicedeliverOrder. OverwritingtheaddressdocumenttypemightbreakthedeliverOrderflowserviceandany otherservicesthatinvokeddeliverOrder. SeethewebMethodsIntegrationServerAdministratorsGuideforinformationabout configuringtheBroker.SeethewebMethodsDeveloperUsersGuideforinformationabout lockingelementsandaccesspermissions(ACLs). To create a publishable document type from an existing Broker document type 1 2 3 OntheFilemenu,clickNew. SelectDocument Type andclickNext. IntheNewDocumentTypedialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefolderinwhichyouwanttosavethedocument type. IntheNamefield,typeanamefortheISdocumenttypeusingacombinationof letters,numbers,and/ortheunderscorecharacter.Forinformationaboutnaming restrictions,seethewebMethodsDeveloperUsersGuide. ClickNext.

Publish-Subscribe Developers Guide Version 7.1

60

5. Working with Publishable Document Types

SelectBroker Document Type,andclickNext.DeveloperopenstheNewDocumentType dialogbox.

IntheNewDocumentTypedialogbox,dothefollowing: a IntheBroker Namespacefield,selecttheBrokerdocumenttypefromwhichyou wanttocreateanISdocumenttype.TheBroker Namespacefieldlistsallofthe BrokerdocumenttypesontheBrokerterritorytowhichtheIntegrationServeris connected. IfyouwanttoreplaceexistingelementsintheNavigationpanelwithidentically namedelementsreferencedbytheBrokerdocumenttype,selecttheOverwrite existing elements when importing referenced elementscheckbox. Important! Overwritingtheexistingelementscompletelyreplacestheexisting elementwiththecontentofthereferencedelement.Anyelementsonthe IntegrationServerthatdependonthereplacedelement,suchasflowservices,IS documenttypes,andspecifications,mightbeaffected.Formoreinformation aboutoverwritingexistingelements,seeImportingandOverwriting Referencesonpage 85.

ClickFinish.DeveloperautomaticallyrefreshestheNavigationpanelanddisplays besidethedocumenttypenametoindicateitisapublishabledocumenttype.

Notes: YoucanassociateonlyonepublishabledocumenttypewithagivenBrokerdocument type.IfyoutrytocreateapublishabledocumenttypefromaBrokerdocumenttype thatisalreadyassociatedwithapublishabledocumenttypeonyourIntegration Server,Developerdisplaysanerrormessage. InthePropertiespanel,theBroker doc type propertydisplaysthenameoftheBroker documenttypeusedtocreatethepublishabledocumenttype.Or,ifyouarenot

Publish-Subscribe Developers Guide Version 7.1

61

5. Working with Publishable Document Types

connectedtoaBroker,thisfielddisplaysPublishableLocallyOnly.Youcannotedit thecontentsofthisfield.Formoreinformationaboutthecontentsofthisfield,see AbouttheAssociatedBrokerDocumentTypeNameonpage 62. TocreateaBrokerdocumenttypeforapublishabledocumenttypethatispublishable locallyonly,pushthepublishabledocumenttypetotheBrokerduring synchronization.Formoreinformationaboutsynchronizing,seeSynchronizing PublishableDocumentTypesonpage 75. ThepublishabledocumenttypeyoucreatefromaBrokerdocumenttypehasthesame publicationpropertiesasthesourceBrokerdocumenttype OnceapublishabledocumenttypehasanassociatedBrokerdocumenttype,youneed tomakesurethatthedocumenttypesremaininsync.Thatis,changesinone documenttypemustbemadetotheassociateddocumenttype.Youcanupdateone documenttypewithchangesintheotherbysynchronizingthem.Forinformation aboutsynchronizingdocumenttypes,seeSynchronizingPublishableDocument Typesonpage 75.

About the Associated Broker Document Type Name


Foradocumenttype,thecontentsoftheBroker doc typepropertycanindicatethe following: Whetherornotthedocumenttypeispublishable. WhetherthepublishabledocumenttypewascreatedfromaBrokerdocumenttype thatwasitselfcreatedfromanISdocumenttype. WhetherthepublishabledocumenttypewascreatedfromaBrokerdocumenttype createdinanearlierversionofawebMethodscomponent. Whetherinstancesofthepublishabledocumenttypecanbeusedinlocalpublishes only.Ifthepublishabledocumenttypecanbeusedonlyinlocalpublishes,thereisno correspondingBrokerdocumenttype.

Publish-Subscribe Developers Guide Version 7.1

62

5. Working with Publishable Document Types

ThefollowingtablelistsanddescribesthepossiblecontentsoftheBroker doc type property. Broker doc type property wm::is::folderName::documentTypeName Description ThenameoftheBrokerdocumenttypethat correspondstothepublishabledocumenttype. Thewm::isprefixindicatesthattheBroker documenttypewascreatedfromanISdocument type.(EitherthecurrentdocumenttypeoranIS documenttypecreatedandmadepublishableon anotherIntegrationServer.)Thisprefixdoesnot specifywhichIntegrationServerthesourceIS documenttypeislocatedon. OntheBroker,alldocumenttypescreatedfrom anISdocumenttypearelocatedintheisfolder, whichisasubfolderofthewmfolder.The folderName::documentTypeNameportionofthename furtheridentifieswherethedocumenttypeis locatedontheBroker. Example: wm::is::customerSync::Customer::updateCustomer IndicatestheBrokerdocumenttypeupdateCustomer islocatedinthefollowingseriesoffolders wm::is::customerSync::Customer. folderName::documentTypeName ThenameoftheBrokerdocumenttypethat correspondstothepublishabledocumenttype. Theabsenceofthewm::isprefixindicatesthatthe publishabledocumenttypewasgeneratedfroma Brokerdocumenttypecreatedwithanearlier versionofawebMethodscomponent. Example: Customer::getCustomer IndicatestheBrokerdocumenttypegetCustomeris locatedintheCustomer::folder.

Publish-Subscribe Developers Guide Version 7.1

63

5. Working with Publishable Document Types

Broker doc type property Publishable Locally Only

Description Indicatesthatinstancesofthepublishable documenttypecanbeusedinlocalpublishes only.Thispublishabledocumenttypedoesnot haveacorrespondingBrokerdocumenttype. Whenyoumadethisdocumenttypepublishable, theIntegrationServerwasnotconnectedtoa Broker.SeeConfiguringtheServerinthe webMethodsIntegrationServerAdministrators Guideforinformationaboutconnectingthe IntegrationServertotheBroker. Note: Ifyouwantinstancesofthispublishable documenttypetobepublishedtotheBroker,you needtocreateaBrokerdocumenttypeforthis publishabledocumenttype.WhentheIntegration ServerisconnectedtoaBroker,youcancreatethe Brokerdocumenttypebypushingthe publishabledocumenttypetotheBrokerduring synchronization.Formoreinformationabout synchronizing,seeSynchronizingPublishable DocumentTypesonpage 75.

Not Publishable

IndicatesthatthisISdocumenttypeisnot publishable.ForinformationaboutmakinganIS documenttypepublishable,seeMakinga PublishableDocumentTypeUnpublishableon page 72.

About the Envelope Field


Allpublishabledocumenttypescontainanenvelope(_env)field.Thisfieldisadocument referencetothepub:publish:envelopedocumenttype.Theenvelopeismuchlikeaheaderin anemailmessage.Thepub:publish:envelope documenttypedefinesthecontentandstructure oftheenvelopethataccompaniesthepublisheddocument.Theenveloperecords informationsuchasthesendersaddress,thetimethedocumentwassent,sequence numbers,andotherusefulinformationforroutingandcontrol.

Publish-Subscribe Developers Guide Version 7.1

64

5. Working with Publishable Document Types

Becausethe_envfieldisneededforpublication,Developercontrolstheusageofthe_env fieldinthefollowingways: Youcannotinsertan_envfieldinadocumenttype.Developerautomaticallyinserts the_envfieldasthelastfieldinthedocumenttypewhenyoumakethedocument typepublishable. Youcannotcopyandpastethe_envfieldfromonedocumenttypetoanother.Youcan copyandpastethisfieldtotheInput/Outputtaborintoaspecification. Youcannotmove,rename,cut,ordeletethe_envfieldfromadocumenttype. Developerautomaticallyremovesthe_envfieldwhenyoumakeadocumenttype unpublishable. The_envfieldisalwaysthelastfieldinapublishabledocumenttype. Formoreinformationaboutthe_envfieldandthecontentsofthepub:publish:envelope documenttype,seethewebMethodsIntegrationServerBuiltInServicesReference. Note: IfanISdocumenttypecontainsafieldnamed_env,youneedtodeletethatfield beforeyoucanmaketheISdocumenttypepublishable.

About Adapter Notifications and Publishable Document Types


Adapternotificationsdeterminewhetheraneventhasoccurredontheadaptersresource andthensendsthenotificationdatatotheIntegrationServerintheformofapublished document.Therearetwotypesofadapternotifications:pollingnotifications,whichpoll theresourceforeventsthatoccurontheresource,andlistenernotifications,whichwork withlistenerstodetectandprocesseventsthatoccurontheadapterresource. Forexample,ifyouareusingtheJDBCAdapterandachangeoccursinadatabasetable thatanadapternotificationismonitoring,theadapternotificationpublishesadocument containingdatafromtheeventandsendsittotheIntegrationServer. Eachadapternotificationhasanassociatedpublishabledocumenttype .Whenyou createanadapternotificationinDeveloper,theIntegrationServerautomaticallygenerates acorrespondingpublishabledocumenttype.Developerassignsthepublishable documenttypethesamenameastheadapternotification,butappendsPublishDocument tothename.Youcanusetheadapternotificationpublishabledocumenttypeintriggers andflowservicesjustasyouwouldanyotherpublishabledocumenttype. Theadapternotificationpublishabledocumenttypeisdirectlytiedtoitsassociated adapternotification.Infact,youcanonlymodifythepublishabledocumenttypeby modifyingtheadapternotification.TheIntegrationServerautomaticallypropagatesthe changesfromtheadapternotificationtothepublishabledocumenttype.Youcannotedit theadapternotificationpublishabledocumenttypedirectly.

Publish-Subscribe Developers Guide Version 7.1

65

5. Working with Publishable Document Types

WhenworkingintheNavigationpanel,Developertreatsanadapternotificationandits publishabledocumenttypeasasingleunit.Ifyouperformanactionontheadapter notificationDeveloperperformsthesameactiononthepublishabledocumenttype.For example,ifyourenametheadapternotification,Developerautomaticallyrenamesthe publishabledocumenttype.Ifyoumove,cut,copy,orpastetheadapternotification Developermoves,cuts,copies,orpastesthepublishabledocumenttype. Forinformationabouthowtocreateandmodifyadapternotifications,seetheappropriate adapterusersguide.

Setting Publication Properties


WhenyouselectapublishabledocumenttypeintheNavigationpanel,itspropertiesare displayedinthePropertiespanel.Foreachpublishabledocumenttype,youcanselecta storagetype,setatimetolivevalue,andspecifywhetherIntegrationServervalidates publishedinstancesofthedocumenttype.Thefollowingsectionsprovidemore informationabouttheseproperties. Note: ChangingaPublicationpropertycausesthepublishabledocumenttypetobeoutof syncwiththeassociatedBrokerdocumenttype.Forinformationaboutsynchronizing documenttypes,seeSynchronizingPublishableDocumentTypesonpage 75.

Selecting a Document Storage Type


Forapublishabledocumenttype,youcansetthestoragetypetodeterminehowthe IntegrationServerandBrokerstoreinstancesofthisdocument.Thestoragetypealso determineshowquicklythedocumentmovesthroughthewebMethodssystem.Youcan selectoneofthefollowingstoragetypes: Volatile storagespecifiesthatinstancesofthepublishabledocumenttypearestoredin memory.VolatiledocumentsmovethroughthewebMethodssystemmorequickly thanguaranteeddocumentsbecauseresourcesdonotreturnacknowledgementsfor volatiledocuments.(Anacknowledgementindicatesthatthereceivingresource successfullystoredorprocessedthedocumentandinstructsthesendingresourceto removeitscopyofthedocumentfromstorage.)However,ifavolatiledocumentis locatedonaresourcethatshutsdown,thevolatiledocumentisnotrecoveredwhen theresourcerestarts. TheIntegrationServerprovidesatmostonceprocessingforvolatiledocuments.That is,documentdeliveryandprocessingareattemptedbutnotguaranteedforvolatile documents.TheIntegrationServermightprocessmultipleinstancesofavolatile document,butonlyifthedocumentwaspublishedmorethanonce.Specifyvolatile storagefordocumentsthathaveashortlifeorarenotcritical. Guaranteed storage specifiesthatinstancesofthepublishabledocumenttypearestored ondisk.Resourcesreturnacknowledgementsafterstoringorprocessingguaranteed

Publish-Subscribe Developers Guide Version 7.1

66

5. Working with Publishable Document Types

documents.Becauseguaranteeddocumentsaresavedtodiskandacknowledged, guaranteeddocumentsmovethroughthewebMethodssystemmoreslowlythan volatiledocuments.However,ifaguaranteeddocumentislocatedonaresourcethat shutsdown,theresourcerecoverstheguaranteeddocumentuponrestart. webMethodscomponentsprovideguaranteeddocumentdeliveryandguaranteed processing(eitheratleastonceprocessingorexactlyonceprocessing)forguaranteed documents.Guaranteedprocessingensuresthatonceatriggerreceivesthedocument,it isprocessed.Useguaranteedstoragefordocumentsthatyoucannotaffordtolose. Note: SomeBrokerdocumenttypeshaveastoragetypeofPersistent.ThePersistent storagetypeautomaticallymapstotheguaranteedstoragetypeintheIntegration Server.

To assign the storage type for a publishable document type 1 2 IntheNavigationpanel,openthepublishabledocumenttypeforwhichyouwantto setthestoragetype. Inthe Propertiespanel,nexttotheStorage typeproperty,selectoneofthefollowing: Select... Guaranteed Volatile To... Specifythatinstancesofthispublishabledocumenttype shouldbestoredondisk. Specifythatinstancesofthispublishabledocumenttype shouldbestoredinmemory.

OntheFilemenu,clickSavetosaveyourchanges.

Important! FordocumentspublishedtotheBroker,thestoragetypeassignedtoadocument canbeoverriddenbythestoragetypeassignedtotheclientqueueontheBroker.Formore information,seeDocumentStorageVersusClientQueueStorageonpage 67.

Document Storage Versus Client Queue Storage


TheBrokercanoverridethestoragetypeassignedtoadocumentwiththestoragetype assignedtotheclientqueue.Aclientqueuecanhaveastoragetypeofvolatileor guaranteed.Volatileclientqueuescancontainvolatiledocumentsonly.Guaranteedclient queuescancontainguaranteeddocumentsandvolatiledocuments. WhentheBrokerreceivesadocument,itplacesthedocumentinclientqueuecreatedfor thesubscriber(suchasatrigger).IftheBrokerreceivesaguaranteeddocumenttowhicha volatileclientqueuesubscribes,theBrokerchangesthestoragetypeofthedocumentfrom guaranteedtovolatilebeforeplacingitinthevolatileclientqueue.TheBrokerdoesnot

Publish-Subscribe Developers Guide Version 7.1

67

5. Working with Publishable Document Types

changethestoragetypeofavolatiledocumentbeforeplacingitinaguaranteedclient queue. Thefollowingtableindicateshowtheclientqueuestoragetypeaffectsthedocument storagetype. If document storage type is... Volatile And the client queue storage type is... Volatile Guaranteed Guaranteed Volatile Guaranteed The Broker saves the document as... Volatile Volatile Volatile Guaranteed

Note: OntheBroker,eachclientqueuebelongstoaclientgroup.Theclientqueuestorage typepropertyassignedtotheclientgroupdeterminesthestoragetypeforalloftheclient queuesintheclientgroup.Youcansettheclientqueuestoragetypeonlywhenyoucreate theclientgroup.Bydefault,theBrokerassignsaclientqueuestoragetypeofguaranteed fortheclientgroupcreatedforIntegrationServers.Formoreinformationaboutclient groups,seethewebMethodsBrokerAdministratorsGuide.

Setting the Time-to-Live for a Publishable Document Type


Thetimetolivevalueforapublishabledocumenttypedetermineshowlonginstancesof thatdocumenttyperemainontheBroker.ThetimetolivecommenceswhentheBroker receivesadocumentfromapublishingIntegrationServer.Ifthetimetoliveexpires beforetheBrokerdeliversthedocumentandreceivesanacknowledgementofdocument receipt,theBrokerdiscardsthedocument.Thishappensforvolatileaswellasguaranteed documents. Forexample,supposethatthetimetoliveforapublishabledocumenttypeis10minutes. WhentheBrokerreceivesaninstanceofthatpublishabledocumenttype,theBrokerstarts timing.If10minuteselapseandtheBrokerhasnotdeliveredthedocumentorreceivedan acknowledgementofdocumentreceipt,theBrokerdiscardsthedocument. Forapublishabledocumenttype,youcansetatimetolivevalueorindicatethatthe Brokershouldneverdiscardinstancesofthedocumenttype.

Publish-Subscribe Developers Guide Version 7.1

68

5. Working with Publishable Document Types

To set a time-to-live value for a publishable document type 1 2 IntheNavigationpanel,openthepublishabledocumenttypeforwhichyouwantto setatimetolive. Inthe Propertiespanel,nexttotheDiscardproperty,selectoneofthefollowing: Select... False True To... SpecifythattheBrokershouldneverdiscardinstancesofthis publishabledocumenttype. SpecifythattheBrokershoulddiscardinstancesofthis publishabledocumenttypeafterthespecifiedtimeelapses. IntheTime to liveproperty,specifythetimetolivevalueand unitsinwhichthetimeshouldbemeasured. 3 OntheFilemenu,clickSavetosaveyourchanges.

Note: Changingapublicationpropertycausesthepublishabledocumenttypetobeoutof syncwiththeassociatedBrokerdocumenttype.Forinformationaboutsynchronizing documenttypes,seeSynchronizingPublishableDocumentTypesonpage 75.

Specifying Validation for a Publishable Document Type


Inapublishandsubscribesolution,IntegrationServervalidatesapublisheddocument againsttheassociatedpublishabledocumenttype.Validationoccursimmediatelyafter thepublishingserviceexecutes.IfIntegrationServerdeterminesthatthepublished documentisinvalid(thatis,thepublisheddocumentdoesnotconformtotheassociated publishabledocumenttype),thepublishingservicereturnsaserviceexceptionthat indicatesthevalidationerror.IntegrationServerdoesnotpublishthedocumentto webMethodsBrokeror,inthecaseoflocalpublishing,tothedispatcher. Whiledocumentvalidationensuresthatdocumentsubscribersreceivevaliddocuments only,itcanbeanexpensiveoperationintermsofresourcesandperformance.Insome situations,youmightnotwanttovalidatethepublisheddocument.Forexample,you mightwanttodisabledocumentvalidationwhenpublishingdocumentsthatwere alreadyvalidated.Supposethatabackendresource,createdandvalidatedthedocument andthensentittoIntegrationServer.IfIntegrationServerinturn,publishesthe documenttoBroker,youmightnotneedtovalidatethedocumentwhenpublishingit becauseitwasalreadyvalidatedbythebackendresource.Youmightalsowanttodisable alldocumentvalidationwhenpublishingnativeBrokerevents.

Publish-Subscribe Developers Guide Version 7.1

69

5. Working with Publishable Document Types

IntegrationServerprovidestwosettingsthatyoucanusetoconfigurevalidationfor publisheddocuments. Aglobalsettingnamedwatt.server.publish.validateOnISthatindicateswhether IntegrationServeralwaysperformsvalidation,neverperformsvalidation,or performsvalidationonaperdocumenttypebasis.Youcansetthispropertyusing IntegrationServerAdministrator.Formoreinformationaboutsettingthisproperty, seethewebMethodsIntegrationServerAdministratorsGuide. Apublicationpropertyforpublishabledocumenttypesthatindicateswhether instancesofapublishabledocumenttypeshouldbevalidated.IntegrationServer honorsthevalueofthisproperty(namedValidate when published)onlyifthe watt.server.publish.validateOnISissettoperDoc(thedefault). Note: Whendecidingwhethertodisabledocumentvalidation,besuretoweighthe advantagesofapossibleincreaseinperformanceagainsttherisksofpublishing,routing, andprocessinginvaliddocuments. Thefollowingprocedureexplainshowtoenableordisablevalidationforindividual publishabledocumenttypes. To specify validation for instances of a publishable document type 1 2 IntheNavigationpanelinDeveloper,openthepublishabledocumenttypeforwhich youwanttospecifyvalidation. InthePropertiespanel,underPublication,settheValidate when publishedpropertyto oneofthefollowing: Select... True To... Performvalidationforpublishedinstancesofthispublishable documenttype. Thisisthedefault. False Disablevalidationforpublishedinstancesofthispublishable documenttype.

OntheFilemenu,clickSave.

Notes: IntegrationServerignoresthevalueoftheValidate when publishedpropertyifthewatt. server.publish.validateOnIS propertyissettoalwaysornever. webMethodsBrokercanalsobeconfiguredtovalidatethecontentsofapublished document.WhenitreceivesthedocumentfromanIntegrationServer,Brokerchecks thevalidationleveloftheBrokerdocumenttypeassociatedwiththepublished

Publish-Subscribe Developers Guide Version 7.1

70

5. Working with Publishable Document Types

document.IfthevalidationlevelissettoFullorOpen,Brokervalidatesthedocument contents.IfthevalidationlevelissettoNone,Brokerdoesnotvalidatethedocument contents.Bydefault,BrokerassignsBrokerdocumenttypescreatedfroma publishabledocumenttypeonanIntegrationServeravalidationlevelofNone.For moreinformationaboutconfiguringdocumentvalidationontheBroker,seethe webMethodsBrokerAdministratorsGuide.

Modifying Publishable Document Types


Youcanmodifyapublishabledocumenttypebychangingitsname,editingitsfieldsor properties,orevenchangingthedocumenttypefrompublishabletounpublishable.This sectiondescribeshowtorenameapublishabledocumenttypeandhowtochangea documenttypefrompublishabletounpublishable. Ifyoumakeachangetoapublishabledocumenttype,keepinmindthatanychange impactsallservices,triggers,specifications,anddocumentfieldsthatuseorreferencethat documenttype.(Theassociatedelementsareimpactedwhenyousavetheupdated documenttypetotheIntegrationServer.) Whenyoumodifyapublishabledocumenttype(forexample,deleteafieldorchangea property),thepublishabledocumenttypeisnolongersynchronizedwiththe correspondingBrokerdocumenttype.Whenyousaveyourchangestothepublishable documenttype,Developerdisplaysamessagestating:
This document type is now out of sync with the associated Broker document type. Use Sync Document Type to synchronize the document type with the Broker.

DeveloperdisplaysthismessageonlyifaBrokerisconfiguredfortheIntegrationServer. Afteryoumodifyapublishabledocumenttype,youneedtoupdatetheassociatedBroker documenttypewiththechanges.Forinformationabouthowtosynchronizedocument types,seeSynchronizingPublishableDocumentTypesonpage 75.

Important Considerations when Editing Publishable Document Types


Keepthefollowingimportantpointsinmindwheneditingpublishabledocumenttypes: Ifyouuseapublishabledocumenttypeastheblueprintforpipelineordocument validation,anychangesyoumaketothepublishabledocumenttypecanaffect whethertheobject(pipelineordocument)beingvalidatedisconsideredvalid.For moreinformationaboutvalidation,seethewebMethodsDeveloperUsersGuide. UseonlyDevelopertoeditapublishabledocumenttype.DonotuseEnterprise IntegratortoeditaBrokerdocumenttypethatcorrespondstoapublishable documenttype.EditingadocumenttypewithEnterpriseIntegratorcanleadto synchronizationproblems.Specifically,changesthatyoumaketoacertaindocument

Publish-Subscribe Developers Guide Version 7.1

71

5. Working with Publishable Document Types

typeswithEnterpriseIntegratorcannotbesynchronizedwiththepublishable documenttypesonIntegrationServer. Changesyoumaketothecontentsofapublishabledocumenttypemightrequireyou tomodifythefilterforthedocumenttypeinatriggercondition.Forexample,ifyou add,rename,ormovefieldsyouneedtoupdateanyfilterthatreferredtothe modifiedfields.Youmightalsoneedtomodifytheservicespecifiedinthetrigger condition.Forinformationaboutfilters,seeCreatingaFilterforaDocumenton page 121.

Renaming a Publishable Document Type


Youcanrenameanypublishabledocumenttypethatisunlockedorforwhichyouown thelock.YoumustalsohaveWriteaccesstothepublishabledocumenttypeanditsparent folder. Whenyourenameapublishabledocumenttype,Developerchecksfordependentssuch astriggersandservicesthatusethepublishabledocumenttype.(Developerperforms dependencycheckingonlyifyouselectthePrompt before updating dependents when renaming/moving checkboxintheOptionsdialogbox.)IfDeveloperfindselementsthatuse thepublishabledocumenttype,Developergivesyoutheoptionofupdatingthe publishabledocumenttypenameineachoftheseelements.Ifyoudonotupdatethe references,allofthereferencestothepublishabledocumenttypewillbebroken.For informationaboutautomaticallycheckingfordependentelementswhenrenaming,see thewebMethodsDeveloperUsersGuide. Important! Youmustmanuallyupdateanyservicesthatinvokethepub.publishservicesand specifythispublishabledocumenttypeinthedocumentTypeNameorthe receivedDocumentTypeNameparameter.

Making a Publishable Document Type Unpublishable


YoucanchangeanypublishabledocumenttypetoaregularISdocumenttypebymaking thepublishabledocumenttypeunpublishable.Whenyoumakeadocumenttype unpublishable,youcandecidewhetherornottheassociatedBrokerdocumenttype shouldbedeleted.However,theIntegrationServerpreventsyoufromdeletingthe associatedBrokerdocumenttypeifasubscriptionexistsforit. Triggersandpublishingservicescanonlyusepublishabledocumenttypes.Ifyoumakea publishabledocumenttypeunpublishable,Youcanonlyspecifypublishabledocument typesintriggersandinpublishingservices.Whenyoumakeapublishabledocumenttype

Publish-Subscribe Developers Guide Version 7.1

72

5. Working with Publishable Document Types

unpublishable,youneedtoupdatetriggersorpublishingservicesthatusedthe publishabledocumenttype. Note: Ifapublishingservicespecifiesthepublishabledocumenttypeandyoumakethe documenttypeunpublishable,thepublishingservicewillnotexecutesuccessfully.The nexttimetheserviceexecutes,theIntegrationServerthrowsaserviceexceptionstating thatthespecifieddocumenttypeisnotpublishable.Formoreinformationabout publishingservices,seeThePublishingServicesonpage 92.

To make a publishable document type unpublishable 1 2 3 IntheNavigationpanel,openthepublishabledocumenttypethatyouwanttomake unpublishable. InthePropertiespanel,nexttoPublishable,selectFalse. OntheFilemenu,clickSavetosaveyourchanges.Ifthedocumenttypeisassociated withaBrokerdocumenttype,DeveloperdisplaystheDeleteConfirmationdialog box.ThisdialogboxpromptsyoutospecifywhethertheassociatedBrokerdocument typeshouldbedeletedorretained. IfyouwouldliketodeletetheassociatedBrokerdocumenttypefromtheBroker,click Yes.Otherwise,clickNo.

Note: YoucanonlydeletetheassociatedBrokerdocumenttypeiftherenoclientshave subscriptionsforit. Developerdisplays besidethedocumenttypenameintheNavigationpanelto indicateitisanISdocumenttypeandcannotbepublished.InthePropertiespanel, DeveloperchangesthecontentsoftheBroker doc typepropertytoNotPublishable.For moreinformationaboutthisfield,seeAbouttheAssociatedBrokerDocumentType Nameonpage 62.

Deleting Publishable Document Types


Whenyoudeleteapublishabledocumenttype,youcandothefollowing: DeletethepublishabledocumenttypeontheIntegrationServeranddeletethe correspondingdocumenttypeontheBroker. DeletethepublishabledocumenttypeontheIntegrationServer,butleavethe correspondingdocumenttypeontheBroker.

Publish-Subscribe Developers Guide Version 7.1

73

5. Working with Publishable Document Types

Beforeyoudeleteapublishabledocumenttype,keepthefollowinginmind: YoucanonlydeletetheassociatedBrokerdocumenttypeiftherearenosubscriptions forit. IfyouintendtodeletetheassociatedBrokerdocumenttypeaswell,makesurethat theBrokerisconfiguredandtheIntegrationServerisconnectedtoit. YoucanonlydeleteapublishabledocumenttypeifyouownthelockandhaveWrite permissiontoit.Formoreinformationaboutaccesspermissions(ACLs),seethe webMethodsDeveloperUsersGuide. To delete a publishable document type 1 2 IntheNavigationpanelofDeveloper,selectthedocumenttypeyouwanttodelete. OntheEdit menu,clickDelete. IfyouenabledthedeletingsafeguardsintheOptionsdialogbox,andthepublishable documenttypeisusedbyotherelements,Developerdisplaysadialogboxlistingall dependentelements,includingtriggersandflowservices. Forinformationaboutenablingsafeguardstocheckfordependentswhendeletingan element,seethewebMethodsDeveloperUsersGuide. 3 Dooneofthefollowing: IfyouwanttodeletethepublishabledocumenttypeontheIntegrationServer, butleavethecorrespondingdocumenttypeontheBroker,leavetheDelete associated Broker document type on the Brokercheckboxcleared. IfyouwanttodeletethepublishabledocumenttypeontheIntegrationServerand thecorrespondingdocumenttypeontheBroker,selecttheDelete associated Broker document type on the Brokercheckbox. 4 Dooneofthefollowing: Click... Continue Cancel OK To... DeletetheelementfromtheNavigationpanel.Referencesin dependentelementsremain. CanceltheoperationandpreservetheelementintheNavigation panel. DeletetheelementfromtheNavigationpanel.(Thisbuttononly appearsifthepublishabledocumenttypedidnothaveany dependents.)

Publish-Subscribe Developers Guide Version 7.1

74

5. Working with Publishable Document Types

Important! IfyoudeleteaBrokerdocumenttypethatisrequiredbyanotherIntegration Server,youcansynchronize(push)thedocumenttypetotheBrokerfromthat IntegrationServer.IfyoudeleteaBrokerdocumenttypethatisrequiredbyanonIS Brokerclient,youcanrecoverthedocumentfromtheBroker.adlbackupfile.Seethe webMethodsBrokerAdministratorsGuideforinformationaboutimporting.adlfiles.

Synchronizing Publishable Document Types


Whenyousynchronizedocumenttypes,youmakesurethatapublishabledocumenttype matchesitsassociatedBrokerdocumenttype.Youwillneedtosynchronizedocument typeswhen: Youmakechangestothepublishabledocumenttype. YoumakechangestotheBrokerdocumenttype.(Thisisusuallytheresultofa developeronanotherIntegrationServerupdatingthatserverscopyofthe publishabledocumenttypeandpushingthechangetotheBrokerdocumenttype.) Youmakechangestobothdocumenttypes. YoumadeadocumenttypepublishablewhentheIntegrationServerwasnot connectedtotheBroker. YouinstallpackagescontainingpublishabledocumenttypesontheIntegration Server. YouchangetheclientgrouptowhichtheIntegrationServerbelongs. Thefollowingsectionsprovideinformationaboutusingsynchronizationactionsand synchronizationstatustokeepdocumenttypesinsync.

Synchronization Status
EachpublishabledocumenttypeonyourIntegrationServerhasasynchronizationstatus toindicatewhetheritisinsyncwiththeBrokerdocumenttype,outofsyncwiththe Brokerdocumenttype,ornotassociatedwithaBrokerdocumenttype.Thefollowing tableidentifieseachpossiblesynchronizationstatusforadocumenttype. Status Updated Locally Updated on Broker Description Thepublishabledocumenttypehasbeenmodifiedonthe IntegrationServer. Thepublishabledocumenttypehasbeenmodifiedonthe Broker.

Publish-Subscribe Developers Guide Version 7.1

75

5. Working with Publishable Document Types

Status Updated Both Locally and on the Broker

Description ThepublishabledocumenttypeandtheBrokerdocumenttype havebothbeenmodifiedsincethelastsynchronization.You mustdecidewhichdefinitionistherequiredoneandpushto orpullfromtheBrokeraccordingly.Informationinoneorthe otherdocumenttypeisoverwritten. Thepublishabledocumenttypewasmadepublishablewhen theBrokerwasnotconnectedorthepublishabledocument typewasloadedontheIntegrationServerviapackage replication.AnassociatedBrokerdocumenttypemayormay notexistontheBroker.IfanassociatedBrokerdocumenttype existsontheBroker,synchronizethedocumenttypesby pullingfromtheBroker.IfnoassociatedBrokerdocument typeexistsontheBroker,create(andsynchronize)the documenttypesbypushingtotheBroker. TheBrokerdocumenttypeassociatedwiththepublishable documenttypewasremovedfromtheBroker.Ifyouwantto recreatethedocumenttypeontheBroker,pushthe publishabledocumenttypetotheBroker.Ifyouwanttodelete thepublishabledocumenttypeontheIntegrationServer,pull fromtheBroker. TheIntegrationServerdocumenttypeandtheBroker documenttypearealreadysynchronized.Noactionis required.

Created Locally

Removed from Broker

In Sync with Broker

Important! SwitchingyourIntegrationServerconnectionfromoneBrokertoBrokerina differentterritoryisneitherrecommendednorsupported.Insuchaswitch,the IntegrationServerdisplaysthesynchronizationstatusasitwasbeforetheswitch.This synchronizationstatusmaybeinaccuratebecauseitdoesnotapplytoelementsthatexist onthesecondBroker.

Synchronization Actions
Whenyousynchronizedocumenttypes,youdecideforeachpublishabledocumenttype whethertopushorpullthedocumenttypetotheBroker.Whenyoupushthepublishable documenttypetotheBroker,youupdatetheBrokerdocumenttypewiththepublishable documenttypeonyourIntegrationServer.Whenyoupullthedocumenttypefromthe Broker,youupdatethepublishabledocumenttypeonyourIntegrationServerwiththe Brokerdocumenttype.

Publish-Subscribe Developers Guide Version 7.1

76

5. Working with Publishable Document Types

Thefollowingtabledescribestheactionsyoucantakewhensynchronizingapublishable documenttype. Action Push to Broker Pull from Broker Skip Description UpdatetheBrokerdocumenttypewithinformationfromthe publishabledocumenttype. Updatethepublishabledocumenttypewithinformationfromthe Brokerdocumenttype. Skipthesynchronizationactionforthisdocumenttype.(Thisaction isonlyavailablewhenyousynchronizemultipledocumenttypesat onetime.)

TheIntegrationServerdoesnotautomaticallysynchronizedocumenttypesbecauseyou mightneedtomakedecisionsaboutwhichversionofthedocumenttypeiscorrect.For example,supposethatIntegrationServer1andIntegrationServer2containidentical publishabledocumenttypesnamedCustomer:getCustomer.Thesepublishabledocument typeshaveanassociatedBrokerdocumenttypenamedwm::is::Customer::getCustomer.Ifa developerupdates Customer:getCustomeronIntegrationServer2andpushesthechangeto theBroker,theBrokerdocumenttypewm::is::Customer::getCustomerisupdated.However,the BrokerdocumenttypeisnowoutofsyncwithCustomer:getCustomeronIntegrationServer1. ThedeveloperusingIntegrationServer1mightnotwantthechangesmadetothe Customer:getCustomerdocumenttypebythedeveloperusingIntegrationServer2.The developerusingIntegrationServer1candecidewhethertoupdatetheCustomer:getCustomer documenttypewhensynchronizingdocumenttypeswiththeBroker. Note: ForasubscribingIntegrationServertoprocessanincomingdocumentsuccessfully, thepublishabledocumenttypeonasubscribingIntegrationServerneedstobeinsync withthecorrespondingdocumenttypesonthepublishingIntegrationServerandthe Broker.Ifthedocumenttypesareoutofsync,thesubscribingIntegrationServermaynot beabletoprocesstheincomingdocuments.Inthiscase,thesubscribingIntegrationServer logsanerrormessagestatingthattheBrokerCodercannotdecodedocument;the documentdoesnotconformtothedocumenttype,documentTypeName.

Publish-Subscribe Developers Guide Version 7.1

77

5. Working with Publishable Document Types

Combining Synchronization Action with Synchronization Status


TheeffectofasynchronizationactiononapublishabledocumenttypeoraBroker documenttypedependsonthesynchronizationstatusofthepublishabledocumenttype. Thefollowingtabledescribestheresultofthepushorpullactionforeachpossible documenttypestatus. Status Updated Locally Action Push to Broker Pull from Broker Result UpdatestheBrokerdocumenttypewithchanges madetothepublishabledocumenttype. Restoresthepublishabledocumenttypetothe previouslysynchronizedversion.Anychanges madetothepublishabledocumenttypeare overwritten. RestorestheBrokerdocumenttypetothe previouslysynchronizedversion.Anychanges madetotheBrokerdocumenttypeare overwritten. Updatesthepublishabledocumenttypewith changesmadetotheBrokerdocumenttype. UpdatestheBrokerdocumenttypewithchanges madetothepublishabledocumenttype.Any changesmadetotheBrokerdocumenttypeprior tosynchronizationareoverwritten. Updatesthepublishabledocumenttypewith changesmadetotheBrokerdocumenttype.Any changesmadetothepublishabledocumenttype priortosynchronizationareoverwritten. IfnoassociatedBrokerdocumenttypeexists,this actioncreatesanassociatedBrokerdocument type.IfanassociatedBrokerdocumenttype alreadyexists,thisactionupdatestheBroker documenttypewiththechangesinthe publishabledocumenttype. Note: IfpublishabledocumenttypesforthisBroker documenttypeexistonotherIntegrationServers, thisactionchangesthesynchronizationstatusof thosepublishabledocumenttypestoUpdated on Broker.

Updated on Broker

Push to Broker

Pull from Broker Updated Both Locally and on the Broker Push to Broker

Pull from Broker

Created Locally

Push to Broker

Publish-Subscribe Developers Guide Version 7.1

78

5. Working with Publishable Document Types

Status

Action Pull from Broker

Result IfanassociatedBrokerdocumenttypeexists,this actionestablishestheassociationbetweenthe documenttypes.Ifchangeshavebeenmadetothe Brokerdocumenttype,thisactionupdatesthe publishabledocumenttypeaswell. IfanassociatedBrokerdocumenttypedoesnot exist,thisactiondeletesthepublishabledocument type. Note: IfpublishabledocumenttypesforthisBroker documenttypeexistonotherIntegrationServers, thisactiondoesnotaffectthesynchronization statusofthosepublishabledocumenttypes.

Removed from Broker In Sync with the Broker

Push to Broker Pull from Broker Push to Broker

RecreatestheBrokerdocumenttype. Deletesthepublishabledocumenttype. Pushesthepublishabledocumenttypetothe Broker.Eventhoughnochangesweremadetothe Brokerdocumenttype,ifotherIntegrationServers containpublishabledocumenttypesassociated withtheBrokerdocumenttype,thestatusofthose publishabledocumenttypesbecomesUpdated onBroker. Tip! Ifapublishabledocumenttypeisinsyncwith theBrokerdocumenttype,settheactiontoSkip.

Pull from Broker

Updatesthepublishabledocumenttypewiththe Brokerdocumenttypeeventhoughnochanges aremade. Tip! Ifapublishabledocumenttypeisinsyncwith theBrokerdocumenttype,settheactiontoSkip.

Note: Forapublishabledocumenttypecreatedforanadapternotification,youcanselect SkiporPush to Brokeronly.Apublishabledocumenttypeforanadapternotificationcan onlybemodifiedontheIntegrationServeronwhichitwascreated.

Publish-Subscribe Developers Guide Version 7.1

79

5. Working with Publishable Document Types

Synchronizing One Document Type


YoucansynchronizeasinglepublishabledocumenttypewithitscorrespondingBroker documenttype.Whenyousynchronizeonepublishabledocumenttype,keepthe followingpointsinmind: IfyouwanttoPull from Broker,youneedtohavewriteaccesstothepublishable documenttypeandownthelockonit.Formoreinformationaboutlockingelements andaccesspermissions(ACLs),seethewebMethodsDeveloperUsersGuide. WhenyouPull from Broker,Developergivesyoutheoptionofoverwritingelements withthesamenamethatalreadyexistontheIntegrationServer.TheBroker documenttypemightreferenceelementssuchasanISschemaorotherISdocument types.IftheIntegrationServeryouareimportingtoalreadycontainsanyelements withthereferencednames,youneedtoknowifthereisanydifferencebetweenthe existingelementsandthosebeingimportedfromtheBroker.Iftherearedifferences, youneedtounderstandwhattheyareandhowimportingthemwillaffectany integrationsolutionthatusesthem.Formoreinformationaboutoverwritingexisting elements,seeImportingandOverwritingReferencesonpage 85. Forapublishabledocumenttypecreatedforanadapternotification,youcanonly selectPush to BrokerorSkip. To synchronize a single publishable document type 1 2 InNavigationpanelofDeveloper,selectthepublishabledocumenttypethatyou wanttosynchronize. SelectFile box. Sync Document Types Selected.DeveloperdisplaystheSynchronizedialog

TheSynchronizedialogboxdisplaysthesynchronizationstatusofthedocument type,asdescribedinSynchronizationStatusonpage 75:

Publish-Subscribe Developers Guide Version 7.1

80

5. Working with Publishable Document Types

UnderAction,dooneofthefollowing: Select... Push to Broker Pull from Broker To... UpdatetheBrokerdocumenttypewiththepublishable documenttype. UpdatethepublishabledocumenttypewiththeBroker documenttype.

Note: Theresultofasynchronizationactiondependsonthedocumentstatus.For moreinformationabouthowtheresultofasynchronizationstatusdependsonthe synchronizationstatus,seeCombiningSynchronizationActionwith SynchronizationStatusonpage 78. 4 5 IfyouselectPull from Broker,astheaction,DeveloperenablestheOverwrite existing elements when importing referenced elementscheckbox. IfyouwanttoreplaceexistingelementsintheNavigationpanelwithidentically namedelementsreferencedbytheBrokerdocumenttype,selecttheOverwrite existing elements when importing referenced elementscheckbox.SeeImportingandOverwriting Referencesonpage 85formoreinformationaboutthistopic. ClickSynchronizetosynchronizethetwodocumenttypes.

Synchronizing Multiple Document Types Simultaneously


YoucansynchronizemultiplepublishabledocumenttypeswiththeircorrespondingBroker documenttypesatonetime.Foreachpublishabledocumenttype,youcanspecifythe directionofthesynchronization.Thatis,foreachdocumenttyperequiringsynchronization, youcanpushthepublishabledocumenttypetotheBrokerorpulltheBrokerdocument typefromtheBroker.Ifyoudonotwanttosynchronizesomepublishabledocumenttypes thatareoutofsync,youcanskipthemduringsynchronization. Tosynchronizemultipledocumenttypesatonce,youcanuseoneofthefollowingdialog boxes: Sync All Out-of-Sync Document Types.Usethisdialogboxtoviewandsynchronizeall publishabledocumenttypesthatareoutsyncwiththeirassociatedBrokerdocument type.Thisdialogboxdisplaysonlypublishabledocumenttypesthatareoutofsync withtheirBrokerdocumenttypes.Thatis,theSyncAllOutofSyncDocumentTypes dialogboxdoesnotdisplaypublishabledocumenttypeswithastatusofInSync withBroker. Sync All Document Types.Usethisdialogboxtoviewandsynchronizeallpublishable documenttypesregardlessofsyncstatus.Thisdialogboxdisplaysinsyncdocument typesinadditiontooutofsyncdocumenttypes.

Publish-Subscribe Developers Guide Version 7.1

81

5. Working with Publishable Document Types

Tip! WhenyouswitchtheBrokerconfiguredfortheIntegrationServertoaBrokerina differentterritory,theIntegrationServerdisplaysthesynchronizationstatusasitwas beforetheswitch.Thissynchronizationstatusmaybeinaccuratebecauseitdoesnot applytoelementsthatexistonthesecondBroker.Toviewandsynchronizeall publishabledocumenttypes,usetheSyncAllDocumentTypesdialogbox. TheSyncAllDocumentTypesdialogboxisdisplayedbelow.


Sync All Document Types dialog box

ForeachpublishabledocumenttypethatisoutofsyncontheIntegrationServer,theSync AllOutofSyncDocumentTypesdialogboxandtheSyncAllDocumentTypesdialog boxdisplaysthefollowinginformation. Field Document Type Description Thenameandiconofthepublishabledocumenttype.Theicon indicatesthelockstatusofthepublishabledocumenttype.Ifared checkmarkappearsnexttothepublishabledocumenttypeicon, anotheruserhaslockedthedocumenttype.Whenapublishable documenttypeislockedbyanotheruser,youcanonlypushtothe Broker.IfyouwanttopullfromtheBroker,youneedtoownthelock onthepublishabledocumenttype(greencheckmark)orthe publishabledocumenttypeneedstobeunlocked.SeethewebMethods DeveloperUsersGuideforinformationaboutlockingobjects.

Publish-Subscribe Developers Guide Version 7.1

82

5. Working with Publishable Document Types

Field Status Action Writable

Description ThestatusofthedocumenttypesasdescribedinSynchronization Statusonpage 75. ApushtotheBroker,pullfromtheBroker,oraskipasdescribedin SynchronizationActionsonpage 76. Indicateswhetheryouhavewritepermissiontothepublishable documenttype.YoucanonlypullfromtheBrokerifyouhavewrite permission.Ifyoudonothavewritepermission,youcanonlypush toBroker.SeethewebMethodsDeveloperUsersGuideforinformation aboutACLpermissions.

Keepthefollowingpointsinmindwhensynchronizingmultipledocumenttypesusing theSyncAllOutofSyncDocumentTypesdialogboxortheSyncAllDocumentTypes dialogbox. IfyouwanttoPull from Broker,youmusthavewriteaccesstothepublishable documenttype.Thepublishabledocumenttypemustbeeitherunlocked,oryoumust havelockedityourself.Formoreinformationaboutlockingelementsandaccess permissions(ACLs),seethewebMethodsDeveloperUsersGuide. WhenyoupulldocumenttypesfromtheBroker,Developergivesyoutheoptionof overwritingelementswiththesamenamethatalreadyexistontheIntegrationServer. TheBrokerdocumenttypemightreferenceelementssuchasanISschemaorotherIS documenttypes.IftheIntegrationServeryouareimportingtoalreadycontainsany elementswiththereferencednames,youneedtoknowifthereisanydifference betweentheexistingelementsandthosebeingimportedfromtheBroker.Ifthereare differences,youneedtounderstandwhattheyareandhowimportingthemwill affectanyintegrationsolutionthatusesthem.Formoreinformationabout overwritingexistingelements,seeImportingandOverwritingReferenceson page 85. Forapublishabledocumenttypecreatedforanadapternotification,youcanonly selectPush to BrokerorSkip.Apublishabledocumenttypeforanadapternotification canonlybemodifiedontheIntegrationServeronwhichitwascreated. To synchronize multiple document types 1 InDeveloper,dooneofthefollowing: Toviewandsynchronizeonlyoutofsyncdocumenttypes,selectFile Sync Document Types All Out-of-Sync.DeveloperdisplaystheSyncAllOutofSync DocumentTypesdialogbox. Toviewandsynchronizealldocumenttypes,regardlessofsyncstatus,select File Sync Document Types All.DeveloperdisplaystheSyncAllDocumentTypes dialogbox.

Publish-Subscribe Developers Guide Version 7.1

83

5. Working with Publishable Document Types

Ifyouwanttospecifythesamesynchronizationactionforallofthepublishable documenttypes,dooneofthefollowing: Select... Set All to Push To... ChangetheActionforallpublishabledocumenttypesinthelist toPush to Broker. Note: WhenyouselectSet All to Push,Developersetsthe publicationactionforadapternotificationdocumenttypesto Skip. Set All to Pull Set All to Skip ChangetheActionforallpublishabledocumenttypesinthelist toPull from Broker. ChangetheActionforallpublishabledocumenttypesinthelist toSkip.

Ifyouwanttospecifyadifferentsynchronizationactionforeachpublishable documenttype,usetheActioncolumntoselectthesynchronizationaction. Select... Push to Broker Pull from Broker Skip To... UpdatetheBrokerdocumenttypewiththepublishable documenttype. UpdatethepublishabledocumenttypewiththeBroker documenttype. Skipthesynchronizationactionforthisdocumenttype.

Note: Theresultofasynchronizationactiondependsonthedocumentstatus.For moreinformationabouthowtheresultofasynchronizationstatusdependsonthe synchronizationstatus,seeCombiningSynchronizationActionwith SynchronizationStatusonpage 78. 4 IfyouwanttoreplaceexistingelementsintheNavigationpanelwithidentically namedelementsreferencedbytheBrokerdocumenttype,selecttheOverwrite existing elements when importing referenced elementscheckbox.Formoreinformationabout importingreferencedelementsduringsynchronization,seeImportingand OverwritingReferencesonpage 85. ClickSynchronizetoperformthespecifiedsynchronizationactionsforoftheallthe listedpublishabledocumenttypes.

Publish-Subscribe Developers Guide Version 7.1

84

5. Working with Publishable Document Types

Synchronizing Document Types in a Cluster


TheBrokerprovidessupportforaclusteredconfigurationofIntegrationServers,thatis, anenvironmentinwhichmultipleIntegrationServersareconfiguredtobehaveasone IntegrationServerconnectedtotheBroker.Achangeinapublishabledocumenttypeon oneIntegrationServerdoesnotautomaticallyresultinachangetoallIntegrationServers inthecluster.YoumustsynchronizeeachIntegrationServerwiththeBrokerindividually.

Synchronizing Document Types Across a Gateway


webMethodsdoesnotsupportsynchronizationofdocumenttypesacrossagateway.(A gatewayconnectstwoBrokerterritories.)IfyousetuptwoormoreBrokerterritories connectedbygateways,theonlywaytosynchronizedocumenttypesistoreplicate packagesbetweenIntegrationServersineachterritory.Forinformationaboutreplicating andloadingpackagesfromoneIntegrationServertoanotherseeManagingPackagesin thewebMethodsIntegrationServerAdministratorsGuide.

Importing and Overwriting References


WhenyoucreateapublishabledocumenttypefromaBrokerdocumenttypeor synchronizeapublishabledocumenttypebypullingaBrokerdocumenttypefromthe Broker,youmustdecideifyouwanttooverwriteanyexistingelementsassociatedwith theBrokerdocumenttype. Forexample,supposethatyouarecreatingapublishabledocumenttypefromaBroker documenttypethatwascreatedonanotherIntegrationServer.TheBrokerdocumenttype mightreferenceelementssuchasanISschemaorotherISdocumenttypes.However,the IntegrationServeronwhichyouarecreatingthepublishabledocumenttypemight alreadycontainelementswiththereferencednames.Beforeyouoverwritetheexisting elements,youneedtoknowifthereareanydifferencesbetweentheexistingelementsand thosebeingimportedfromtheBroker.Iftherearedifferences,youneedtounderstand whattheyareandhowimportingthemwillaffectanyelementsthatusethem,suchas services,ISdocumenttypes,ortriggers. WhenyoucreateanewdocumenttypefromaBrokerdocumenttypeorwhenyou synchronizedocumenttypes,youcanusetheOverwrite existing elements when importing referenced elementscheckboxtoindicatewhetherexistingelementsshouldbeoverwritten byimportedelementsofthesamename.

Publish-Subscribe Developers Guide Version 7.1

85

5. Working with Publishable Document Types

What Happens When You Overwrite Elements on the Integration Server?


Ifyouchoosetooverwriteexistingelementswhenyouarecreatingadocumenttypeor synchronizing,theIntegrationServerdoesthefollowingwhenitencountersexisting elementswiththesamenamesasreferencedelements: IftheWriteACLofareferencedelementissettoWmPrivate,theIntegrationServer skipsthatelement.TheIntegrationServerconsiderstheelementtobeinsync. Ifthelockcanbeobtainedforallreferencedelementsandthecurrentuserhaswrite permissionfortheelements,theIntegrationServeroverwritestheexistingelements andsynchronization(ordocumenttypecreation)succeeds. Duringsynchronization,iftheIntegrationServercannotoverwriteoneoftheelements referencedbytheBrokerdocumenttype,thesynchronizationfails.TheIntegrationServer doesnotupdateanyofthereferencedelementsorthepublishabledocumenttype. Similarly,whenyoucreateapublishabledocumenttypefromaBrokerdocumenttype,if theIntegrationServercannotoverwriteoneoftheelementsreferencedbytheBroker documenttype,theIntegrationServerdoesnotcreatethepublishabledocumenttype. Whenyousynchronizemultipledocumenttypes,theIntegrationServerupdatesallthe documenttypesforwhichitcanupdateallofthereferencedelements.IftheIntegration Serverencountersareferencedelementforwhichitcannotobtainalockortheuserdoes nothavewriteaccess,theIntegrationServerskipssynchronizationofthatdocumenttype anditsreferencedelements.

What Happens if You Do Not Overwrite Elements on the Integration Server?


Ifyouchoosenottooverwriteelementswhenyoucreateapublishabledocumenttype fromaBrokerdocumenttype,theIntegrationServerwillnotcreatethepublishable documenttypeiftheBrokerdocumenttypereferenceselementswiththesamenameas existingelementsontheIntegrationServer. Ifyouchoosenottooverwriteelementswhenyousynchronizedocumenttypesbypulling fromtheBroker,theIntegrationServerdoesnotsynchronizeanydocumenttypethat referencesexistingelementsontheIntegrationServer.TheIntegrationServer synchronizesonlythosedocumenttypesthatdonotreferenceelements.

Testing Publishable Document Types


YoucantestapublishabledocumenttypeusingtoolsprovidedinDeveloper.Whenyou testapublishabledocumenttype,youprovideinputvaluesthatDeveloperusestocreate aninstanceofthepublishabledocumenttype.Youalsospecifyapublishingmethod(such

Publish-Subscribe Developers Guide Version 7.1

86

5. Working with Publishable Document Types

aspublish,publishandwait,deliver,ordeliverandwait).Developerthenpublishesa documentanddisplaystheresultsofthepublishintheResultspanel. Testingapublishabledocumenttypeprovidesawayforyoutopublishadocument withoutbuildingaservicethatdoestheactualpublishing.Ifyouselectapublication actionwhereyouwaitforareplydocument,youcanverifywhetherornotreply documentsarereceived. Note: Whenyoutestapublishabledocumenttype,theIntegrationServeractually publishesthedocumentlocallyortotheBroker(whicheverisspecified). Ifyouwanttotestajoinconditioninatrigger,youmighttesteachpublishabledocument typeidentifiedinthejoincondition.Ifyoudothis,makesuretousethesameactivation numberforeachpublishabledocumenttypethatyoutest. Note: IfyourpublishabledocumenttypeexpectsObjectvariablesthatdonothave constraintsassignedoranObjectdefinedasabyte[],youwillnotbeabletoenterthose valuesintheInputdialogbox.Totestthesevalues,youmustwriteaJavaservicethat generatesinputvaluesforyourserviceandaflowservicethatpublishesthedocument. Then,createaflowservicethatfirstinvokestheJavaserviceandthenthepublishingflow service.

To test a publishable document type 1 2 3 IntheNavigationpanel,openthepublishabledocumenttypethatyouwanttotest. Click totestthepublishabledocumenttype.DeveloperdisplaystheInputfor PublishableDocumentTypeNamedialogbox. IntheInputforPublishableDocumentTypeNamedialogbox,entervalidvaluesforthe fieldsdefinedinthepublishabledocumenttypeorclicktheLoadbuttontoretrievethe valuesfromafile.Forinformationaboutloadinginputvaluesfromafile,seethe webMethodsDeveloperUsersGuide. Ifyouwanttosavetheinputvaluesthatyouhaveentered,clickSave.Inputvalues thatyousavecanberecalledandreusedinlatertests.Forinformationaboutsaving inputvalues,seethewebMethodsDeveloperUsersGuide. ClickNext.WhenyouentervaluesforconstrainedobjectsintheInputdialogbox, IntegrationServerautomaticallyvalidatesthevalues.Ifthevalueisnotofthetype specifiedbytheobjectconstraint,Developerdisplaysamessageidentifyingthe variableandtheexpectedtype.

Publish-Subscribe Developers Guide Version 7.1

87

5. Working with Publishable Document Types

IntheRuntestforPublishableDocumentTypeNamedialogbox,selectthetypeof publishingforthedocument. Select... Publish locally to this Integration Server Publish locally to this Integration Server and wait for a Reply Publish to a Broker Publish to a Broker and wait for a Reply Deliver to a specific Client Deliver to a specific Client and wait for a Reply To... Publishaninstanceofthepublishabledocument typetothesameIntegrationServertowhichyou areconnected. Publishaninstanceofthepublishabledocument typetothesameIntegrationServertowhichyou areconnectedandwaitforaresponsedocument. Publishaninstanceofthispublishabledocument typetotheBroker. Publishaninstanceofthispublishabledocument typetotheBrokerandwaitforaresponse document. Deliveraninstanceofthepublishabledocument typetoaspecificclientontheBroker. Deliveraninstanceofthepublishabledocument typetoaspecificclientontheBrokerandwaitfor areplydocument.

7 8

ClickNextorFinish. IfyouselectedeitherDeliver to a specific ClientorDeliver to a specific Client and wait for a Reply,intheRuntestforPublishableDocumentTypeNamedialogbox,selecttheBroker clienttowhichyouwanttodeliverthedocument.ClickNext orFinish. Note: Inthisdialogbox,DeveloperdisplaysalltheclientsconnectedtoyourBroker. TheIntegrationServerassignstriggerclientsnamesaccordingtotheclientprefix specifiedontheSettings > BrokerscreenoftheIntegrationServerAdministrator.

Publish-Subscribe Developers Guide Version 7.1

88

5. Working with Publishable Document Types

Ifyouselectedapublicationactioninwhichyouwaitforareply,youneedtoselect thedocumenttypethatyouexpectasareply.Developerdisplaysallthepublishable documenttypesontheIntegrationServertowhichyouarecurrentlyconnected. a IntheNamefield,typethefullyqualifiednameofthepublishabledocumenttype thatyouexpectasareplyorselectitfromtheFolderlist.Iftheservicedoesnot expectaspecificdocumenttypeasareply,leavethisfieldblank. UnderSet how long Developer waits for a Reply,selectoneofthefollowing: Select... Never discard To... SpecifythatDevelopershouldwaitindefinitelyforareply document.Developerwillwaitfortheresponseforthe lengthofyoursessionontheIntegrationServer.When youendyoursessionorcloseDeveloper,Developerstops waitingforthereply. SpecifythelengthoftimethatDevelopershouldwaitfor thereplydocument. NexttotheDiscard afteroption,enterhowlongyouwant Developertowaitforthereplydocument. c ClickFinish.Developerpublishesaninstanceofthepublishabledocumenttype.

Discard after

Notes: Developerdisplaystheinstancedocumentandpublishinginformationinthe Resultspanel. Ifyouselectedapublicationactioninwhichyouwaitforareply,andDeveloper receivesareplydocument,Developerdisplaysthereplydocumentasthevalueof thereceiveDocumentTypeNamefieldintheResultspanel IfDeveloperdoesnotreceivethereplydocumentbeforethetimespecifiednext Discard afterelapses,Developerdisplaysanerrormessagesstatingthatthepublish andwait(ordeliverandwait)hastimedout.TheResultspaneldisplaysnullnext tothereceiveDocumentTypeNamefieldtoindicatethattheIntegrationServerdid notreceiveareplydocument.

Publish-Subscribe Developers Guide Version 7.1

89

5. Working with Publishable Document Types

Publish-Subscribe Developers Guide Version 7.1

90

Chapter 6. Publishing Documents

The Publishing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Setting Fields in the Document Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Publishing a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Publishing a Document and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Delivering a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Delivering a Document and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Replying to a Published or Delivered Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Publish-Subscribe Developers Guide Version 7.1

91

6. Publishing Documents

The Publishing Services


Usingthepublishingservices,youcancreateservicesthatpublishordeliverdocuments locallyortotheBroker.ThepublishingservicesarelocatedintheWmPublicpackage. Thefollowingtabledescribestheservicesyoucanusetopublishdocuments. Service pub.publish:deliver pub.publish:deliverAndWait pub.publish:publish Description Deliversadocumenttoaspecifieddestination. Deliversadocumenttoaspecifieddestinationandwaits foraresponse. PublishesadocumentlocallyortoaconfiguredBroker. Anyclients(triggers)withsubscriptionstodocumentsof thistypewillreceivethedocument. PublishesadocumentlocallyortoaconfiguredBroker andwaitsforaresponse.Anyclients(triggers)with subscriptionsforthepublisheddocumentwillreceivethe document. Deliversareplydocumentinanswertoadocument receivedbytheclient. Retrievesthereplydocumentforarequestpublished asynchronously.

pub.publish:publishAndWait

pub.publish:reply pub.publish:waitForReply

Setting Fields in the Document Envelope


Thedocumentenvelopecontainsinformationaboutthepublisheddocument,suchasthe publishersclientID,theclienttowhicherrornotificationsshouldbesent,auniversally uniqueidentificationnumber,andtheroutethedocumenthastakenthroughthesystem. Thedocumentenvelopecontainsread/writefieldsaswellasreadonlyfields.The

Publish-Subscribe Developers Guide Version 7.1

92

6. Publishing Documents

followingtableidentifiestheread/writeenvelopefieldsthatyoumightwanttosetwhen buildingaservicethatpublishesdocuments. Field name errorsTo Description AStringthatspecifiestheclientIDtowhichtheIntegrationServer sendsanerrornotificationdocument(aninstanceof pub.publish.notify:error)iferrorsoccurduringdocumentprocessingby subscribers. IfyoudonotspecifyavalueforerrorsTo,errornotificationsaresentto thedocumentpublisher. replyTo AStringthatspecifieswhichclientIDrepliestothepublished documentshouldbesentto.IfyoudonotspecifyareplyTo destination,responsesaresenttothedocumentpublisher. Important! Whenyoucreateaservicethatpublishesadocumentand waitsforareply,donotsetthevalueofthereplyTofieldinthe documentenvelope.Bydefault,theIntegrationServerusesthe publisherIDasthereplyTovalue.IfyouchangethereplyTovalue, responseswillnotbedeliveredtothewaitingservice. activation AStringthatspecifiestheactivationIDforthepublisheddocument.If adocumentdoesnothaveanactivationID,theIntegrationServer automaticallyassignsanactivationIDwhenitpublishesthe document. SpecifyanactivationIDwhenyouwantatriggertojointogether documentspublishedbydifferentservices.Inthiscase,assignthe sameactivationIDtothedocumentsintheservicesthatpublishthe documents.FormoreinformationabouthowtheIntegrationServer usesactivationIDstosatisfyjoinconditions,seeChapter 9, UnderstandingJoinConditions. Formoreinformationaboutthefieldsinthedocumentenvelope,seethedescriptionofthe pub.publish envelopedocumenttypeinthewebMethodsIntegrationServerBuiltInServices Reference.

Publish-Subscribe Developers Guide Version 7.1

93

6. Publishing Documents

About the Activation ID


AnactivationIDisauniqueidentifierassignedtoapublisheddocument.Subscribing triggersusetheactivationIDtodeterminewhetheradocumentsatisfiesajoincondition. TheIntegrationServerstorestheactivationIDintheactivationfieldofadocument envelope. Bydefault,theIntegrationServerassignsthesameactivationIDtoeachdocument publishedwithinasingletoplevelservice.Forexample,supposetheprocessPOservice publishesanewCustomerdocument,acheckInventorydocument,andaconfirmOrderdocument. BecauseallthreedocumentsarepublishedwithintheprocessPOservice,theIntegration ServerassignsallthreedocumentsthesameactivationID. YoucanoverridethedefaultbehaviorbyassigninganactivationIDtoadocument manually.Forexample,inthepipeline,youcanmapavariabletotheactivationfieldofthe document.IfyouwanttoexplicitlysetadocumentsactivationID,youmustsetitbefore publishingthedocument.Whenpublishingthedocument,theIntegrationServerwillnot overwriteanexplicitlysetvaluefortheactivationfield. YouneedtosettheactivationIDforadocumentonlywhenyouwantatriggertojoin togetherdocumentspublishedbydifferentservices.Ifatriggerwilljointogether documentspublishedwithinthesameexecutionofaservice,youdonotneedtosetthe activationID.TheIntegrationServerautomaticallyassignsallthedocumentsthesame activationID. Tip! Ifaservicepublishesanewdocumentasaresultofreceivingadocument,andyou wanttocorrelatethenewdocumentwiththereceiveddocument,considerassigningthe activationIDofthereceiveddocumenttothenewdocument.

Publishing a Document
Whenyoupublishadocumentusingthepub.publish:publishservice,thedocumentis broadcast.Theservicepublishesthedocumentforanyinterestedsubscribers.Any subscriberstothedocumentcanreceiveandprocessthedocument.

Publish-Subscribe Developers Guide Version 7.1

94

6. Publishing Documents

How to Publish a Document


Thefollowingdescribesthegeneralstepsyoutaketocreateaservicethatpublishesa document. 1 Create a document reference to the publishable document type that you want to publish.You canaccomplishthisby: Declaringadocumentreferenceintheinputsignatureofthepublishingservice OR InsertingaMAPstepinthepublishingserviceandaddingthedocument referencetoPipelineOut.Youmustimmediatelylinkorassignavaluetothe documentreference.Ifyoudonot,Developerautomaticallyclearsthedocument referencethenexttimeitrefreshesthePipelinetab. 2 Add content to the document reference.Youcanaddcontentbylinkingfieldstothe documentreferenceorbyusingtheSet Valuemodifier inthedocumentreference. 3 toassignvaluestothefields

Assign values to fields in the envelope (_env field) of the document reference.Whenaservice oradapternotificationpublishesadocument,theIntegrationServerandtheBroker automaticallyassignvaluestomanyfieldsinthedocumentenvelope.However,you canmanuallysetsomeofthesefields.TheIntegrationServerandBrokerdonot overwritefieldsthatyousetmanually.Formoreinformationaboutassigningvalues tofieldsinthedocumentenvelope,seeSettingFieldsintheDocumentEnvelopeon page 92. Invoke pub.publish:publish to publish the document.Thisservicetakesthedocumentyou createdandpublishesit. Thepub.publish:publishserviceexpectstofindadocument(IDataobject)named documentinthepipeline.Ifyouarebuildingaflowservice,youwillneedtousethe Pipelinetabtomapthedocumentyouwanttopublishtodocument. Inadditiontothedocumentreferenceyoumapintodocument,youmustprovidethe followingparametertopub.publish:publish. Name documentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypethatyouwanttopublish.The publishabledocumenttypemustexistontheIntegration Server.

Publish-Subscribe Developers Guide Version 7.1

95

6. Publishing Documents

Youmayalsoprovidethefollowingoptionalparameters: Name local Description AStringindicatingwhetheryouwanttopublishthe documentlocally.Whenyoupublishadocument locally,theIntegrationServerdoesnotsendthe documenttotheBroker.Thedocumentremainsonthe publishingIntegrationServer.Onlysubscribersonthe sameIntegrationServercanreceiveandprocessthe document. Note: IfaBrokerisnotconfiguredforthisIntegration Server,theIntegrationServerautomaticallypublishes thedocumentlocally.Youdonotneedtosentthelocal parametertotrue. Set to...
true false

To... Publishthedocumentlocally. Publishthedocumenttotheconfigured Broker.Thisisthedefault.

delayUntilServiceSuccess

AStringspecifyingthattheIntegrationServerwilldelay publishingthedocumentuntilthetoplevelservice executessuccessfully.Ifthetoplevelservicefails,the IntegrationServerwillnotpublishthedocument. Set to...


true

To... Delaypublishinguntilafterthetoplevel serviceexecutessuccessfully. Note: IntegrationServerdoesnotreturna statuswhenthisparameterissettotrue.

false

Publishthedocumentwhenthepublish serviceexecutes.

Publish-Subscribe Developers Guide Version 7.1

96

6. Publishing Documents

Note: Thewatt.server.control.maxPublishOnSuccessparametercontrolsthe maximumnumberofdocumentsthattheIntegrationServercanpublishonsuccessatone time.Youcanusethisparametertopreventtheserverfromrunningoutofmemorywhen aservicepublishesmany,largedocumentsonsuccess.Bydefault,thisparameterissetto 50,000documents.Decreasethenumberofdocumentsthatcanbepublishedonsuccessto helppreventanoutofmemoryerror.Formoreinformationaboutthisparameter,seethe webMethodsIntegrationServerAdministratorsGuide.

Publishing a Document and Waiting for a Reply


AservicecanrequestinformationfromotherresourcesinthewebMethodssystemby publishingadocumentthatcontainsaqueryfortheinformation.Servicesthatpublisha requestdocument,waitforandthenprocessareplydocumentfollowtherequest/reply model.Therequest/replymodelisavariationofthepublishandsubscribemodel.Inthe request/replymodel,apublishingclientbroadcastsarequestforinformation.Subscribers retrievethebroadcastdocument,processit,andsendareplydocumentthatcontainsthe requestedinformationtothepublisher. Aservicecanimplementasynchronousorasynchronousrequest/reply. Inasynchronousrequest/reply,thepublishingservicestopsexecutingwhileitwaits foraresponsetoapublishedrequest.Thepublishingserviceresumesexecutionwhen areplydocumentisreceivedorthespecifiedwaitingtimeelapses. Inanasynchronousrequest/reply,thepublishingservicecontinuestoexecuteafter publishingtherequestdocument.Thepublishingservicemustinvokeanotherservice towaitforandretrievethereplydocument. Ifyouplantobuildaservicethatpublishesmultiplerequestsandretrievesmultiple replies,considermakingtherequestsasynchronous.Youcanconstructtheserviceto publishalltherequestsfirstandthencollectthereplies.Thisapproachcanbemore efficientthanpublishingarequest,waitingforareply,andthenpublishingthenext request. Youcanusethepub.publish:publishAndWaitservicetobuildaservicethatperformsa synchronousoranasynchronousrequest/reply.Ifyouneedaspecificclienttorespondto therequestforinformation,usethepub.publish:deliverAndWaitserviceinstead.Formore informationaboutusingthepub.publish:deliverAndWaitservice,seeDeliveringaDocument andWaitingforaReplyonpage 104. ForinformationabouthowtheIntegrationServerandBrokerprocessarequestandreply, seePublishingDocumentsandWaitingforaReplyonpage 23.

Publish-Subscribe Developers Guide Version 7.1

97

6. Publishing Documents

How to Publish a Request Document and Wait for a Reply


Thefollowingdescribesthegeneralstepsyoutaketocodeaservicethatpublishesa requestdocumentandwaitsforareply. 1 Create a document reference to the publishable document type that you want to publish.You canaccomplishthisby: Declaringadocumentreferenceintheinputsignatureofthepublishingservice. OR InsertingaMAPstepinthepublishingserviceandaddingthedocument referencetoPipeline Out.Youmustlinkorassignavaluetothedocument referenceimmediately.Ifyoudonot,Developerautomaticallyclearsthedocument referencethenexttimeitrefreshesthePipelinetab. 2 Add content to the document reference.Youcanaddcontentbylinkingfieldstothe documentreferenceorbyusingtheSet Valuemodifier inthedocumentreference. 3 toassignvaluestothefields

Assign values to fields in the envelope (_env field) of the document reference.Whenaservice oradapternotificationpublishesadocument,theIntegrationServerandtheBroker automaticallyassignvaluestofieldsinthedocumentenvelope.However,youcan manuallysetsomeofthesefields.TheIntegrationServerandBrokerdonotoverwrite fieldsthatyousetmanually.Formoreinformationaboutassigningvaluestothe documentenvelope,seeSettingFieldsintheDocumentEnvelopeonpage 92. Important! Whenyoucreateaservicethatpublishesadocumentandwaitsforareply, donotsetthevalueofthereplyTofieldinthedocumentenvelope.Bydefault,the IntegrationServerusesthepublisherIDasthereplyTovalue.IfyouchangethereplyTo value,responseswillnotbedeliveredtothewaitingservice.

Invoke pub.publish:publishAndWait to publish the document.Thisservicetakesthe documentyoucreatedandpublishesit. Thepub.publish:publishAndWaitserviceexpectstofindadocument(IDataobject)named documentinthepipeline.Ifyouarebuildingaflowservice,youwillneedtousethe Pipelinetabtomapthedocumentyouwanttopublishtodocument. Inadditiontothedocumentreferenceyoumapintodocument,youmustprovidethe followingparameterstopub.publish:publishAndWait. Name documentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypethatyouwanttopublishan instanceof.Thepublishabledocumenttypemustexiston theIntegrationServer.

Publish-Subscribe Developers Guide Version 7.1

98

6. Publishing Documents

Youmayalsoprovidethefollowingoptionalparameters: Name receiveDocumentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypeexpectedasareply.This publishabledocumenttypemustexistonyour IntegrationServer. IfyoudonotspecifyareceiveDocumentTypeName value,theserviceusesthefirstreplythatitreceives forthisrequest. Important! Ifyouspecifyadocumenttype,youneedto workcloselywiththedeveloperofthesubscribing triggerandthereplyservicetomakesurethatthe replyservicesendsareplydocumentofthecorrect type. local AStringindicatingwhetheryouwanttopublishthe documentlocally.Whenyoupublishadocument locally,thedocumentremainsonthepublishing IntegrationServer.TheIntegrationServerdoesnot publishthedocumenttotheBroker.Onlysubscribers onthesameIntegrationServercanreceiveand processthedocument. Set to...
true false

To... Publishthedocumentlocally. Publishthedocumenttotheconfigured Broker.Thisisthedefault.

waitTime

AStringspecifyinghowlongthepublishingservice waits(inmilliseconds)forareplydocument.Ifyoudo notspecifyawaitTimevalue,theservicewaitsuntilit receivesareply.TheIntegrationServerbegins trackingthewaitTimeassoonasitpublishesthe document.

Publish-Subscribe Developers Guide Version 7.1

99

6. Publishing Documents

Name async

Description AStringindicatingwhetherthisisasynchronousor asynchronousrequest. Set to...


true

To... Indicatethatthisisanasynchronous request.TheIntegrationServerpublishes thedocumentandthenexecutesthenext stepintheservice. Indicatethatthisisasynchronousrequest. TheIntegrationServerpublishesthe documentandthenwaitsforthereply.The IntegrationServerexecutesthenextstepin theserviceonlyafteritreceivesthereply documentorthewaittimeelapses.Thisis thedefault.

false

Map the tag field to another pipeline variable.Ifthisserviceperformsapublishandwait requestinanasynchronousmanner(asyncissettotrue),thepub.publish:publishAndWait serviceproducesafieldnamedtagasoutput.Thetagfieldcontainsauniqueidentifier thattheIntegrationServerusestomatchtherequestdocumentwithareply document. Ifyoucreateaservicethatcontainsmultipleasynchronousrequests,makesuretolink thetagoutputtoanotherfieldinthepipeline.Eachasynchronouslypublishedrequest producesatagfield.Ifthetagfieldisnotlinkedtoanotherfield,thenext asynchronouslypublishedrequest(thatis,thenextexecutionofthe pub.publish:publishAndWaitserviceorthepub.publish:deliverAndWaitservice)willoverwrite thefirsttagvalue. Note: Thetagvalueproducedbythepub.publish:publishAndWaitserviceisthesamevalue thattheIntegrationServerplacesinthetagfieldoftherequestdocumentsenvelope.

Invoke pub.publish:waitForReply to retrieve the reply document.Ifyouconfiguredthe pub.publish:publishAndWaitservicetopublishandwaitforthedocumentasynchronously, youneedtoinvokethepub.publish:waitForReplyservice.Thisserviceretrievesthereply documentforaspecificrequest. Thepub.publish:waitForReplyserviceexpectstofindaStringnamedtaginthepipeline. (TheIntegrationServerretrievesthecorrectreplybymatchingthetagvalueprovided tothewaitForReplyservicetothetagvalueinthereplydocumentenvelope.)Ifyouare buildingaflowservice,youwillneedtousethePipelinetabtomapthefield containingthetagvalueoftheasynchronouslypublishedrequesttotag.

Publish-Subscribe Developers Guide Version 7.1

100

6. Publishing Documents

Process the reply document.Thepub.publish:publishAndWait(orpub.publish:waitForReply) serviceproducesanoutputparameternamedreceivedDocumentthatcontainsthereply document(anIDataobject)deliveredbyasubscriber. IfthewaitTimeintervalelapsesbeforetheIntegrationServerreceivesareply,the receivedDocumentparametercontainsanulldocument. Note: Asinglepublishandwaitrequestmightreceivemanyresponsedocuments.The IntegrationServerthatpublishedtherequestusesonlythefirstreplydocumentit receivesfromtheBroker.(Ifprovided,thedocumentmustbeofthetypespecifiedin thereceiveDocumentTypeNamefieldofthepub.publish:publishAndWaitservice.)The IntegrationServerdiscardsallotherreplies.Firstisarbitrarilydefined.Thereisno guaranteeprovidedfortheorderinwhichtheBrokerprocessesincomingreplies.If youneedareplydocumentfromaspecificclient,usethepub.publish:deliverAndWait serviceinstead.

Delivering a Document
Deliveringadocumentismuchlikepublishingadocument,exceptthatyouspecifythe clientthatyouwanttoreceivethedocument.TheBrokerroutesthedocumenttothe specifiedsubscriber.Becauseonlyoneclientreceivesthedocument,deliveringa documentessentiallybypassesallthesubscriptionstothedocumentontheBroker.

How to Deliver a Document


Todeliveradocument,youinvokethepub.publish:deliverservice.Thefollowingdescribes thegeneralstepsyoutaketocreateaservicethatdeliversadocumenttoaspecific destination. 1 Create a document reference to the publishable document type that you want to deliver.Youcan accomplishthisby: Declaringadocumentreferenceintheinputsignatureofthepublishingservice OR InsertingaMAPstepinthepublishingserviceandaddingthedocument referencetoPipeline Out.Youmustimmediatelylinkorassignavaluetothe documentreference.Ifyoudonot,Developerautomaticallyclearsthedocument referencethenexttimeitrefreshesthePipelinetab. 2 Add content to the document reference.Youcanaddcontentbylinkingfieldstothe documentreferenceorbyusingtheSet Valuemodifier inthedocumentreference. toassignvaluestothefields

Publish-Subscribe Developers Guide Version 7.1

101

6. Publishing Documents

Assign values to fields in the envelope (_env field) of the document reference.Whenaservice oradapternotificationpublishesadocument,theIntegrationServerandtheBroker automaticallyassignvaluestofieldsinthedocumentenvelope.However,youcan manuallysetsomeofthesefields.TheIntegrationServerandBrokerdonotoverwrite fieldsthatyousetmanually.Formoreinformationaboutassigningvaluestofieldsin thedocumentenvelope,seeSettingFieldsintheDocumentEnvelopeonpage 92. Note: InthePipelinetab,youcanassignvaluesonlytofieldsunderPipeline Outor Service In.

Invoke pub.publish:deliver to deliver the document.Thisservicetakesthedocumentyou createdandpublishesit. Thepub.publish:deliverserviceexpectstofindadocument(IDataobject)nameddocument inthepipeline.Ifyouarebuildingaflowservice,youwillneedtousethePipelinetab tomapthedocumentyouwanttodelivertodocument. Inadditiontothedocumentreferenceyoumapintodocument,youmustprovidethe followingparameterstopub.publish:deliver. Name documentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypethatyouwanttopublish.The publishabledocumenttypemustexistontheIntegration Server. AStringspecifyingtheclientIDtowhichyouwantto deliverthedocument.Youcandeliverthedocumentto anindividualtriggerclientortothedefaultclient(an IntegrationServer).Youcanviewalistoftheclientson theBrokerby: UsingtheBrokerAdministrator. Testingthepublishabledocumenttypeandselecting oneofthedeliveroptions. Note: IfyouspecifyanincorrectclientID,theIntegration ServerdeliversthedocumenttotheBroker,butthe Brokerneverdeliversthedocumenttotheintended recipientandnoerrorisproduced.

destID

Publish-Subscribe Developers Guide Version 7.1

102

6. Publishing Documents

Youmayalsoprovidethefollowingoptionalparameters: Name delayUntilServiceSuccess Description AStringspecifyingthattheIntegrationServerwill delaypublishingthedocumentuntilthetoplevel serviceexecutessuccessfully.Ifthetoplevelservice fails,theIntegrationServerwillnotpublishthe document. Set to...
true

To... Delaypublishinguntilafterthetop levelserviceexecutessuccessfully. Publishthedocumentwhenthe pub.publish:deliverserviceexecutes.Thisis thedefault.

false

Note: Thewatt.server.control.maxPublishOnSuccessparametercontrolsthe maximumnumberofdocumentsthattheIntegrationServercanpublishonsuccessatone time.Youcanusethisparametertopreventtheserverfromrunningoutofmemorywhen aservicepublishesmany,largedocumentsonsuccess.Bydefault,thisparameterissetto 50,000documents.Decreasethenumberofdocumentsthatcanbepublishedonsuccessto helppreventanoutofmemoryerror.Formoreinformationaboutthisparameter,seethe webMethodsIntegrationServerAdministratorsGuide.

Cluster Failover and Document Delivery


Clusterfailoverwillnotoccurforaguaranteeddocumentdeliveredtotheshareddefault clientforaclusterofIntegrationServers.Whentheshareddefaultclientreceivesthe document,itimmediatelyacknowledgesthedocumenttotheBrokerandplacesthe documentinasubscribingtriggerqueueononeoftheIntegrationServernodes.Ifthe receivingIntegrationServerfailsbeforeitprocessesthedocument,anotherserverinthe clustercannotprocessthedocumentbecausethedocumentisstoredlocallyonthe receivingserver.Additionally,theBrokerwillnotredeliverthedocumenttothecluster becausethedefaultclientalreadyacknowledgedthedocumenttotheBroker.The receivingserverwillprocesstheguaranteeddocumentaftertheserverrestarts.(Volatile documentswillbelostiftheresourceonwhichtheyarelocatedfails.)

Publish-Subscribe Developers Guide Version 7.1

103

6. Publishing Documents

Delivering a Document and Waiting for a Reply


YoucaninitiateandcontinueaprivateconversationbetweentwoBrokerclientsby creatingaservicethatdeliversadocumentandwaitsforareply.Thisisavariationofthe request/replymodel.Thepublishingclientexecutesaservicethatdeliversadocument requestinginformationtoaspecificclient.Thesubscribingclientprocessesthedocument andsendsthepublisherareplydocumentthatcontainstherequestedinformation. Aservicecanimplementasynchronousorasynchronousrequest/reply. Inasynchronousrequest/reply,thepublishingservicestopsexecutingwhileitwaits foraresponsetoapublishedrequest.Thepublishingserviceresumesexecutionwhen areplydocumentisreceivedorthespecifiedwaitingtimeelapses. Inanasynchronousrequest/reply,thepublishingservicecontinuestoexecuteafter publishingtherequestdocument.Thepublishingservicemustinvokeanotherservice towaitforandretrievethereplydocument. Ifyouplantobuildaservicethatpublishesmultiplerequestsandretrievesmultiple replies,considermakingtherequestsasynchronous.Youcanconstructtheserviceto publishalltherequestsfirstandthencollectthereplies.Thisapproachcanbemore efficientthanpublishingarequest,waitingforareply,andthenpublishingthenext request. Youcanusethepub.publish:deliverAndWaitservicetobuildaservicethatperformsa synchronousoranasynchronousrequest/reply.Thisservicedeliverstherequest documenttoaspecificclient.Ifmultipleclientscansupplytherequestedinformation, considerusingthepub.publish:publishAndWaitserviceinstead.Formoreinformationabout usingthepub.publish:publishAndWaitservice,seePublishingaDocumentandWaitingfora Replyonpage 97.

How to Deliver a Document and Wait for a Reply


Thefollowingdescribesthegeneralstepsthatyoutaketocodeaservicethatdeliversa documenttoaspecificdestinationandwaitsforareply. 1 Create a document reference to the publishable document type that you want to deliver.Youcan accomplishthisby: Declaringadocumentreferenceintheinputsignatureofthepublishingservice OR InsertingaMAPstepinthepublishingserviceandaddingthedocument referencetoPipelineOut.Youmustimmediatelylinkorassignavaluetothe documentreference.Ifyoudonot,Developerautomaticallyclearsthedocument referencethenexttimeitrefreshesthePipelinetab.

Publish-Subscribe Developers Guide Version 7.1

104

6. Publishing Documents

Add content to the document reference.Youcanaddcontentbylinkingfieldstothe documentreferenceorbyusingtheSet Valuemodifier inthedocumentreference. toassignvaluestothefields

Assign values to fields in the envelope (_env field) of the document reference.Whenaservice oradapternotificationpublishesadocument,theIntegrationServerandtheBroker automaticallyassignvaluestofieldsinthedocumentenvelope.However,youcan manuallysetsomeofthesefields.TheIntegrationServerandBrokerdonotoverwrite fieldsthatyousetmanually.Formoreinformationaboutassigningvaluestofieldsin thedocumentenvelope,seeSettingFieldsintheDocumentEnvelopeonpage 92. Important! Whenyoucreateaservicethatdeliversadocumentandwaitsforareply,do notsetthevalueofthereplyTofieldinthedocumentenvelope.Bydefault,the IntegrationServerusesthepublisherIDasthereplyTovalue.IfyousetthereplyTo value,responsesmaynotbedeliveredtothewaitingservice.

Invoke pub.publish:deliverAndWait to publish the document.Thisservicetakesthe documentyoucreatedandpublishesittotheBroker.TheBrokerdeliversthe documenttotheclientqueuefortheclientyouspecify. Thepub.publish:deliverAndWaitserviceexpectstofindadocument(IDataobject)named documentinthepipeline.Ifyouarebuildingaflowservice,youwillneedtousethe Pipelinetabtomapthedocumentyouwanttopublishtodocument. Inadditiontothedocumentreferenceyoumapintodocument,youmustprovidethe followingparameterstopub.publish:deliverAndWait. Name documentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypethatyouwanttopublish.The publishabledocumenttypemustexistontheIntegration Server. AStringspecifyingtheclientIDtowhichyouwantto deliverthedocument. Note: IfyouspecifyanincorrectclientID,theIntegration ServerdeliversthedocumenttotheBroker,buttheBroker neverdeliversthedocumenttotheintendedrecipientand noerrorisproduced.

destID

Publish-Subscribe Developers Guide Version 7.1

105

6. Publishing Documents

Youmayalsoprovidethefollowingoptionalparameters: Name receiveDocumentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypeexpectedasareply.This publishabledocumenttypemustexistonyour IntegrationServer. IfyoudonotspecifyareceiveDocumentTypeNamevalue, theserviceusesthefirstreplydocumentitreceives fromtheclientspecifiedindestID. Important! Ifyouspecifyadocumenttype,youneedto workcloselywiththedeveloperofthesubscribing triggerandthereplyservicetomakesurethatthe replyservicesendsareplydocumentofthecorrect type. waitTime AStringspecifyinghowlongthepublishingservice waits(inmilliseconds)forareplydocument.Ifyoudo notspecifyawaitTimevalue,theservicewaitsuntilit receivesareply.TheIntegrationServerbeginstracking thewaitTimeassoonasitpublishesthedocument. AStringindicatingwhetherthisisasynchronousor asynchronousrequest. Set to...
true

async

To... Indicatethatthisisanasynchronous request.TheIntegrationServerpublishes thedocumentandthenexecutesthenext stepintheservice. Indicatethatthisisasynchronousrequest. TheIntegrationServerpublishesthe documentandthenwaitsforthereply. TheIntegrationServerexecutesthenext stepintheserviceonlyafteritreceivesthe replydocumentorthewaittimeelapses. Thisisthedefault.

false

Map the tag field to another pipeline variable.Ifthisserviceperformsapublishandwait requestinanasynchronousmanner(asyncissettotrue),thepub.publish:deliverAndWait serviceproducesafieldnamedtagasoutput.Thetagfieldcontainsauniqueidentifier thattheIntegrationServerusestomatchtherequestdocumentwithareply document.

Publish-Subscribe Developers Guide Version 7.1

106

6. Publishing Documents

Ifyoucreateaservicethatcontainsmultipleasynchronousrequests,makesuretolink thetagoutputtoanotherfieldinthepipeline.Eachasynchronouslypublishedrequest producesatagfield.Ifthetagfieldisnotlinkedtoanotherfield,thenext asynchronouslypublishedrequest(thatis,thenextexecutionofthe pub.publish:publishAndWaitserviceorthepub.publish:deliverAndWaitservice)willoverwrite thefirsttagvalue. Note: Thetagvalueproducedbythepub.publish:deliverAndWaitserviceisthesamevalue thattheIntegrationServerplacesinthetagfieldoftherequestdocumentsenvelope. 6 Invoke pub.publish:waitForReply to retrieve the reply document.Ifyouconfiguredthe pub.publish:deliverAndWaitservicetopublishandwaitforthedocumentasynchronously, youneedtoinvokethepub.publish:waitForReplyservice.Thisserviceretrievesthereply documentforaspecificrequest. Thepub.publish:waitForReplyserviceexpectstofindaStringnamedtaginthepipeline. (TheIntegrationServerretrievesthecorrectreplybymatchingthetagvalueprovided tothewaitForReplyservicetothetagvalueinthereplydocumentenvelope.)Ifyouare buildingaflowservice,youwillneedtousethePipelinetabtomapthefield. 7 Process the reply document.Thepub.publish:deliverAndWait(orpub.publish:waitForReply)service producesanoutputparameternamedreceivedDocumentthatcontainsthereply document(anIDataobject)deliveredbyasubscriber. IfthewaitTimeintervalelapsesbeforetheIntegrationServerreceivesareply,the receivedDocumentparametercontainsanulldocument.

Replying to a Published or Delivered Document


Youcancreateaservicethatsendsareplydocumentinresponsetoapublishedor deliveredrequestdocument.Thereplydocumentmightbeasimpleacknowledgementor mightcontaininformationrequestedbythepublisher. Youcanbuildservicesthatsendreplydocumentsinresponsetooneormorereceived documents.Forexample,ifreceivingdocumentAanddocumentBsatisfiesanAll (AND)join condition,youmightcreateaservicethatsendsareplydocumenttothepublisherof documentAandthesamereplydocumenttothepublisherofdocumentB. Tosendareplydocumentinresponsetoadocumentthatyoureceive,youcreateaservice thatinvokesthepub.publish:replyservice. Note: Allreplydocumentsaretreatedasvolatiledocuments.Volatiledocumentsarestored inmemory.Iftheresourceonwhichthereplydocumentisstoredshutsdownbefore processingthereplydocument,thereplydocumentislost.Theresourcewillnotrecoverit uponrestart.

Publish-Subscribe Developers Guide Version 7.1

107

6. Publishing Documents

Specifying the Envelope of the Received Document


Thepub.publish:replyservicecontainsaninputparameternamedreceivedDocumentEnvelope. Thisparameteridentifiestheenvelopeoftherequestdocumentforwhichthisservice createsareply.TheIntegrationServerusestheinformationinthereceiveddocument envelopetomakesureitdeliversthereplydocumenttothecorrectclient. Todeterminewheretosendthereply,theIntegrationServerfirstchecksthevaluereplyTo fieldinthereceiveddocumentenvelope.IfthereplyTofieldspecifiesaclientIDtowhich tosendresponses,theIntegrationServerdeliversthereplydocumenttothatclient.Ifthe replyTofieldcontainsnovalue,theIntegrationServersendsreplydocumentstotheclient IDofthepublisher(whichisspecifiedintheenvelopespubIDfield). Whenyoucodeaservicethatrepliestoadocument,settingthereceivedDocumentEnvelope parameterisoptional.ThisfieldisoptionalbecausetheIntegrationServerusesthe informationinthereceiveddocumentsenvelopetodeterminewheretosendthereply document.IftheserviceexecutesbecausetwoormoredocumentssatisfiedanAll (AND) joincondition,theIntegrationServerusestheenvelopeofthelastdocumentthatsatisfied thejoinconditionasthevalueofthereceivedDocumentEnvelopeparameter.Forexample, supposethatdocumentAanddocumentBsatisfiedanAll (AND)joincondition.IftheIntegration ServerfirstreceivesdocumentAandthenreceivesdocumentB,theIntegrationServerusesthe envelopeofdocumentBasthevalueofreceivedDocumentEnvelope.TheIntegrationServer sendsthereplydocumentonlytotheclientidentifiedintheenvelopeofdocumentB.Ifyou wanttheIntegrationServertoalwaysusetheenvelopeofdocumentA,linktheenvelopeof documentAtoreceivedDocumentEnvelope. Tip! IfyouwantareplyservicetosenddocumentstothepublisherofdocumentAandthe publisherofdocumentB,invokethepub.publish:replyserviceonceforeachdocument.Thatis, youneedtocodeyourservicetocontainonepub.publish:replyservicethatrespondstothe publisherofdocumentAandasecondpub.publish:replyservicethatrespondstothesenderof documentB.

How to Create a Service that Sends a Reply Document


Thefollowingdescribesthegeneralstepsyoutaketocodeaservicethatsendsareply documentinresponsetoareceiveddocument. 1 Declare a document reference to the publishable document type.Intheinputsignatureofthe service,declareadocumentreferencetothepublishabledocumenttypeforthe receiveddocument.Thenameofthedocumentreferencemustbethefullyqualified nameofthepublishabledocumenttype. Ifyouintendtousetheservicetoreplytodocumentsthatsatisfyajoincondition(a conditionthatassociatesmultiplepublishabledocumenttypeswithaservice),the servicesinputsignaturemusthaveadocumentreferenceforeachpublishable documenttype.Thenamesofthesedocumentreferencefieldsmustbethefully qualifiednamesofthepublishabledocumenttypetheyreference.

Publish-Subscribe Developers Guide Version 7.1

108

6. Publishing Documents

Create a document reference to the publishable document type that you want to use as the reply document.Youcanaccomplishthisby: Declaringadocumentreferenceintheinputsignatureofthereplyingservice OR InsertingaMAPstepinthereplyingserviceandaddingthedocumentreference toPipeline Out.Youmustimmediatelylinkorassignavaluetothedocument reference.Ifyoudonot,Developerautomaticallyclearsthedocumentreference thenexttimeitrefreshesthePipelinetab. Note: Ifthepublishingservicerequiresthatthereplydocumentbeaninstanceofa specificpublishabledocumenttype,makesurethatthedocumentreferencevariable referstothispublishabledocumenttype.

Add content to the reply document.Youcanaddcontenttothereplydocumentbylinking fieldstothedocumentreferenceorbyusingtheSet Valuemodifier tothefieldsinthedocumentreference. toassignvalues

Assign values to fields in the envelope (_env field) of the reply document.Whenaserviceor adapternotificationpublishesadocument,theIntegrationServerandtheBroker automaticallyassignvaluestofieldsinthedocumentenvelope.Whenyoucreatea servicethatsendsareplydocument,theIntegrationServerusesthefieldinthe envelopeofthereceiveddocumenttopopulatethereplydocumentenvelope. However,youcanmanuallysetsomeofthesefields.TheIntegrationServerand Brokerdonotoverwritefieldsthatyousetmanually.Formoreinformationabout...., seeSettingFieldsintheDocumentEnvelopeonpage 92. Invoke pub.publish:reply to publish the reply document.Thisservicetakesthereply documentyoucreatedanddeliversittotheclientspecifiedintheenvelopeofthe receiveddocument. Thepub.publish:reply serviceexpectstofindadocument(IDataobject)nameddocument inthepipeline.Ifyouarebuildingaflowservice,youwillneedtousethePipelinetab tomapthedocumentreferenceforthedocumentyouwanttopublishtodocument. Inadditiontothedocumentreferencethatyoumapintodocument,youmustprovide thefollowingparameterstothepub.publish:replyservice. Name documentTypeName Description AStringspecifyingthefullyqualifiednameofthe publishabledocumenttypeforthereplydocument.The publishabledocumenttypemustexistontheIntegration Server.

Publish-Subscribe Developers Guide Version 7.1

109

6. Publishing Documents

Important! Servicesthatpublishordeliverarequestandwaitforareplycanspecifya publishabledocumenttypetowhichreplydocumentsmustconform.Ifthereply documentisnotofthetypespecifiedinreceiveDocumentTypeNameparameterofthe pub.publish:publishAndWaitorpub.publish:deliverAndWaitservice,thepublishingservicewill notreceivethereply.Youneedtoworkcloselywiththedeveloperofthepublishing servicetomakesurethatyourreplydocumentisaninstanceofthecorrect publishabledocumenttype. Youmayalsoprovidethefollowingoptionalparameters. Name receivedDocumentEnvelope Description Adocument(IDataobject)containingtheenvelopeof thereceiveddocument.Bydefault,theIntegration Serverusestheinformationinthereceived documentsenvelopetodeterminewheretosendthe replydocument. Iftheserviceexecutesbecausetwoormoredocuments satisfiedanAll (AND)joincondition,theIntegration Serverusestheenvelopeofthelastdocumentthat satisfiedthejoincondition.IfyouwanttheIntegration Servertoalwaysusetheenvelopefromthesame documenttype,linktheenvelopeofthatpublishable documenttypetoreceivedDocumentEnvelope.Ifyou wanteachdocumentpublishertoreceiveareply document,youmustinvokethepub.publish:replyservice foreachdocumentinthejoin. Important! IfthereplyingserviceexecutesbecauseadocumentsatisfiedanAny (OR)or Only one (XOR)joincondition,donotmaporassignavaluetothe receivedDocumentEnvelope.ItisimpossibletoknowwhichdocumentintheAny (OR)or Only one (XOR)joinwillbereceivedfirst.Forexample,supposethatanOnly one (XOR) joinconditionspecifieddocumenttypesdocumentAanddocumentB.TheIntegration Serverusestheenvelopeofwhicheverdocumentitreceivedfirstasthe receivedDocumentEnvelopevalue.IfyoumaptheenvelopeofdocumentAto receivedDocumentEnvelope,buttheIntegrationServerreceivesdocumentBfirst,thereply servicewillfail.

Publish-Subscribe Developers Guide Version 7.1

110

6. Publishing Documents

Name delayUntilServiceSuccess

Description AStringspecifyingthattheIntegrationServerwill delaypublishingthereplydocumentuntilthetop levelserviceexecutessuccessfully.Ifthetoplevel servicefails,theIntegrationServerwillnotpublishthe replydocument. Set to...


true

To... Delaypublishinguntilafterthetoplevel serviceexecutessuccessfully. Publishthedocumentwhenthe pub.publish:replyserviceexecutes.Thisisthe default.

false

Build a trigger.ForthisservicetoexecutewhentheIntegrationServerreceives documentsofaspecifiedtype,youneedtocreateatrigger.Thetriggerneedsto containaconditionthatassociatesthepublishabledocumenttypeusedfortherequest documentwiththisreplyservice.Formoreinformationaboutcreatingatrigger,see Chapter 7,WorkingwithTriggers.

Publish-Subscribe Developers Guide Version 7.1

111

6. Publishing Documents

Publish-Subscribe Developers Guide Version 7.1

112

Chapter 7. Working with Triggers

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Overview of Building a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Creating a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Setting Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Modifying a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Deleting Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Testing Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Publish-Subscribe Developers Guide Version 7.1

113

7. Working with Triggers

Introduction
Triggersestablishsubscriptionstopublishabledocumenttypesandspecifieshowto processinstancesofthosepublishabledocumenttypes.Whenyoubuildatrigger,you createoneormoreconditions.Aconditionassociatesoneormorepublishabledocument typeswithasingleservice.Thepublishabledocumenttypeactsasthesubscriptionpiece ofthetrigger.Theserviceistheprocessingpiece.Whenthetriggerreceivesdocumentsto whichitsubscribes,theIntegrationServerprocessesthedocumentbyinvokingthe servicespecifiedinthecondition.Triggerscancontainmultipleconditions. Note: WithwebMethodsDeveloper,youcancreateBroker/localtriggersandJMStriggers. ABroker/localtriggeristriggerthatsubscribestoandprocessesdocuments published/deliveredlocallyortotheBroker.AJMStriggerisatriggerthatreceives messagesfromadestination(queueortopic)onaJMSproviderandthenprocessesthose messages.ThisguidediscussesdevelopmentanduseofBroker/localtriggersonly.Where thetermstriggerortriggersappearinthisguide,theyrefertoBroker/localtriggers.

Overview of Building a Trigger


Buildingatriggerisaprocessthatinvolvesthefollowingbasicstages: Stage
1

Description Creating a new trigger on Integration Server.Duringthisstage,youcreatethe newtriggerontheIntegrationServerwhereyouwilldoyourdevelopment andtesting.Formoreinformation,seeCreatingaTriggeronpage 117. Creating one or more conditions for the trigger. Duringthisstage,youassociate publishabledocumenttypeswithservices,createfilterstoapplyto incomingdocuments,andselectjointypes.Formoreinformation,see CreatingaTriggeronpage 117. Setting trigger properties. Duringthisstage,yousetparametersthatconfigure theruntimeenvironmentofthistrigger,suchastriggerqueuecapacity, documentprocessingmode,fatalandtransienterrorhandling,andexactly onceprocessing.Forinformationaboutthisstage,seeSettingTrigger Propertiesonpage 126. Testing and debugging. Duringthisstageyoucanusethetoolsprovidedby Developertotestanddebugyourtrigger.Formoreinformation,see TestingTriggersonpage 150.

Whenyoubuildatrigger,youusetheupperhalfoftheeditortocreate,delete,andorder conditions.Youusethelowerhalfoftheeditortocreateaconditionbyselectingthe publishabledocumenttypestowhichyouwantthetriggertosubscribeandtheservice youwanttheIntegrationServertoexecutewhenitreceivesinstancesofthosedocuments.

Publish-Subscribe Developers Guide Version 7.1

114

7. Working with Triggers

The editor for building triggers

Use the upper half of the editor to create, delete, and order conditions.

Use the lower half of the editor to name the condition... ...and specify the service that should be invoked...

...when instances of this publishable document type are received.

Service Requirements
Theservicethatprocessesadocumentreceivedbyatriggeriscalledatriggerservice.A conditionspecifiesasingletriggerservice. Beforeyoucanenableatrigger,thetriggerservicemustalreadyexistonthesame IntegrationServer.Additionally,theinputsignatureforthetriggerserviceneedstohavea documentreferencetothepublishabledocumenttype.Thenameforthisdocument referencemustbethefullyqualifiednameofthepublishabledocumenttype.Thefully qualifiednameofapublishabledocumenttypeconformstothefollowingformat: folder.subfolder:PublishableDocumentTypeName Forexample,supposethatyouwantatriggertoassociatetheCustomers:customerInfo publishabledocumenttypewiththeCustomers:addToCustomerStoreservice.Onthe Input/Outputtaboftheservice,theinputsignaturemustcontainadocumentreference namedCustomers:customerInfo.

Publish-Subscribe Developers Guide Version 7.1

115

7. Working with Triggers

The trigger service input signature must contain a document reference to the publishable document type

The input signature of this service declares a document reference to... ... this publishable document type.

The name for this document reference must be the fully qualified name of the publishable document type.

Ifyouintendtousetheserviceinajoincondition(aconditionthatassociatesmultiple publishabledocumenttypeswithaservice),theservicesinputsignaturemusthavea documentreferenceforeachpublishabledocumenttype.Thenamesofthesedocument referencefieldsmustbethefullyqualifiednamesofthepublishabledocumenttypethey reference. Tip! Youcaninsertadocumentreferenceintotheinputsignatureofthetargetserviceby draggingthepublishabledocumenttypefromtheNavigationpaneltotheinputsideof theservicesInput/Output tab. Tip! YoucancopyandpastethefullyqualifieddocumenttypenamefromtheNavigation paneltothedocumentreferencefieldname.Tocopythefullyqualifiedname,rightclick thedocumenttypeintheNavigationpanel,andselectCopy.Topastethefullyqualified nameinforthefieldname,rightclickthedocumentreferencefield,selectRename,and pressCTRL+V. Youcanconfigurethetriggerservicetogenerateauditdatawhenitexecutesbysetting Auditpropertiesforthetriggerservice.Ifatriggerservicegeneratesauditdataand includesacopyoftheinputpipelineintheauditlogyoucanusewebMethodsMonitorto reinvokethetriggerserviceatalatertime.Forinformationaboutcreatingservices,

Publish-Subscribe Developers Guide Version 7.1

116

7. Working with Triggers

declaringinputandoutputsignatures,andconfiguringserviceauditing,seethe webMethodsDeveloperUsersGuide. Tip! Youcaninsertadocumentreferenceintotheinputsignatureofthetargetserviceby draggingthepublishabledocumenttypefromtheNavigationpaneltotheinputsideof theservicesInput/Outputtab.

Trigger Validation
Whenyousaveatrigger,theIntegrationServerevaluatesthetriggerandspecifically,the conditionsinthetrigger,tomakesurethetriggerisvalid.IftheIntegrationServer determinesthatthetriggeroraconditioninthetriggerisnotvalid,Developerdisplaysan errormessageandpromptsyoutocancelthesaveorcontinuethesavewithadisabled trigger.TheIntegrationServerconsidersatriggertobevalidwheneachofthefollowing istrue: Thetriggercontainsatleastonecondition. Eachconditioninthetriggerspecifiesauniquename. Eachconditioninthetriggerspecifiesaservice. Eachconditioninthetriggerspecifiesoneormorepublishabledocumenttypes. Ifmultipleconditionsinthetriggerspecifythesamepublishabledocumenttype,the filterappliedtothepublishabledocumenttypemustbethesameineachcondition. Formoreinformationaboutcreatingfilters,seeCreatingaFilterforaDocumenton page 121. Thesyntaxofafilterappliedtoapublishabledocumenttypeiscorrect. Thetriggercontainsnomorethanonejoincondition.

Creating a Trigger
Atriggerdefinesasubscriptiontooneormorepublishabledocumenttypes.Inatrigger, theconditionsthatyoucreateassociateoneormorepublishabledocumenttypeswitha service. Whenyoucreateatrigger,keepthefollowingpointsinmind: Thepublishabledocumenttypesandservicesthatyouwanttouseinconditionsmust alreadyexist.Formoreinformationaboutrequirementsforservicesusedintriggers, seeServiceRequirementsonpage 115. Atriggercansubscribetopublishabledocumenttypesonly subscribetoordinaryISdocumenttypes .Atriggercannot

.ForinformationaboutmakingIS

Publish-Subscribe Developers Guide Version 7.1

117

7. Working with Triggers

documenttypespublishable,seeMakinganExistingISDocumentType Publishableonpage 57. Multipletriggers(andmultipleconditionswithinatrigger)canreferencethesame publishabledocumenttype.Atruntime,foreachtrigger,theIntegrationServer invokestheservicespecifiedforthefirstconditionthatmatchesthepublishable documenttypecriteria. Atriggercancontainonlyonejoincondition(aconditionthatassociatesmorethan onepublishabledocumenttypeswithaservice).Atriggercancontainmultiple simpleconditions(aconditionthatassociatesonepublishabledocumenttypewitha service). Eachconditioninatriggermusthaveauniquename. Youcansaveonlyvalidtriggers.Formoreinformationaboutrequirementsforavalid trigger,seeTriggerValidationonpage 117. Important! Whenyoucreatetriggers,workonastandaloneIntegrationServerinsteadof anIntegrationServerinacluster.Creating,modifying,disabling,andenablingtriggerson anIntegrationServerinaclustercancreateinconsistenciesinthecorrespondingtrigger clientqueuesontheBroker.

To create a trigger 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectTrigger,andclickNext. IntheNewTriggerdialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefolderinwhichyouwanttosavethetrigger. IntheNamefield,typeanameforthetriggerusinganycombinationofletters, and/ortheunderscorecharacter.Foralistofreservedwordsandsymbols,see NamingRulesforwebMethodsDeveloperElementsonpage 218. ClickNext.

c 4 5

InthenewTriggerNamedialogbox,selectBroker/Localtrigger. ClickFinish. DevelopergeneratesthenewtriggeranddisplaysitintheDeveloperwindow. DeveloperautomaticallyaddsanemptyconditionnamedCondition1tothetrigger.

Publish-Subscribe Developers Guide Version 7.1

118

7. Working with Triggers

Intheeditor,usethefollowingproceduretobuildacondition. a IntheNamefield,typethenameyouwanttoassigntothecondition.Developer automaticallyassignseachconditionadefaultnamesuchasCondition1or Condition2.Youcankeepthisnameorchangeittoamoredescriptiveone.You mustspecifyauniquenameforeachconditionwithinatrigger. IntheServicefield,enterthefullyqualifiedservicenamethatyouwantto associatewiththepublishabledocumenttypesinthecondition.Youcantypein theservicename,orclick toselecttheservicefromtheSelectdialogbox.

Note: AnXSLTservicecannotbeusedasatriggerservice. c d UnderDocument types and filters,click .DeveloperdisplaystheSelectoneor morepublishabledocumenttypesdialogbox. IntheSelectoneormorepublishabledocumenttypesdialogbox,selectthe publishabledocumenttypestowhichyouwanttosubscribe.Youcanselectmore thanonepublishabledocumenttypebyusingtheCTRLorSHIFTkeys. Developercreatesarowforeachselectedpublishabledocumenttypeinthetable underDocument types and filters. e IntheFiltercolumnnexttoeachpublishabledocumenttype,enterafilterthatyou wanttheIntegrationServertoapplytoeachinstanceofthispublishable documenttype.TheIntegrationServerexecutesthetriggerserviceonlyif instancesofthedocumenttypemeetthefiltercriteria.Filtersareoptionalfora triggercondition.Formoreinformationaboutfilters,seeCreatingaFilterfora Documentonpage 121. Tip! Clickthe editor. nexttotheFiltercolumntoviewandeditthefilterinalargertext

Publish-Subscribe Developers Guide Version 7.1

119

7. Working with Triggers

Ifyouspecifiedmorethanonepublishabledocumenttypeinthecondition,select ajointype. Join Type All (AND) Description TheIntegrationServerinvokesthetriggerservicewhen theserverreceivesaninstanceofeachspecified publishabledocumenttypewithinthejointimeout period.Theinstancedocumentsmusthavethesame activationID.Thisisthedefaultjointype. FormoreinformationaboutactivationIDs,seeAboutthe ActivationIDonpage 94. Any (OR) TheIntegrationServerinvokesthetriggerservicewhenit receivesaninstanceofanyoneofthespecified publishabledocumenttypes. TheIntegrationServerinvokesthetriggerservicewhenit receivesaninstanceofanyofthespecifieddocument types.Forthedurationofthejointimeoutperiod,the IntegrationServerdiscardsanyinstancesofthespecified publishabledocumenttypeswiththesameactivationID.

Only one (XOR)

Formoreinformationaboutjointypesandjoinconditions,seeChapter 9, UnderstandingJoinConditions. 7 InthePropertiespanel,specifythejointimeoutperiod,triggerqueuecapacity, documentprocessingmode,anddocumentdeliveryattemptsincaseoferror.For moreinformationabouttriggerproperties,seeSettingTriggerPropertieson page 126. InthePropertiespanel,underPermissions,specifytheACLsyouwanttoapplytothe trigger,ifany.SeethewebMethodsDeveloperUsersGuideforinstructionsforthistask. OntheFilemenu,clickSavetosavethetrigger.

8 9

Notes: IntegrationServervalidatesthetriggerbeforesavingit.IfIntegrationServer determinesthatthetriggerisinvalid,Developerpromptsyoutosavethetriggerina disabledstate.Formoreinformationaboutvalidtriggers,seeTriggerValidationon page 117. IntegrationServerestablishesthesubscriptionlocallybycreatingatriggerqueuefor thetrigger.Thetriggerqueueislocatedinthetriggerdocumentstore.Documents retrievedbytheserverremaininthetriggerqueueuntiltheyareprocessed. IfyouareconnectedtotheBroker,IntegrationServerregistersthetrigger subscriptionwiththeBrokerbycreatingaclientforthetriggerontheBroker.

Publish-Subscribe Developers Guide Version 7.1

120

7. Working with Triggers

IntegrationServeralsocreatesasubscriptionforeachpublishabledocumenttype specifiedinthetriggerconditionsandsavesthesubscriptionswiththetriggerclient. IfyouarenotconnectedtoaBrokerwhenyousavethetrigger,thetriggerwillonly receivedocumentspublishedlocally.WhenyoureconnecttoaBroker,thenexttime IntegrationServerrestarts,theIntegrationServerwillcreateaclientforthetriggeron theBrokerandcreatesubscriptionsforthepublishabledocumenttypesidentifiedin thetriggerconditions.TheBrokervalidatesthefiltersinthetriggerconditionswhen IntegrationServercreatesthesubscriptions. Ifapublishabledocumenttypespecifiedinatriggerconditiondoesnotexistonthe Broker(thatis,thereisnoassociatedBrokerdocumenttype),IntegrationServerstill createsthetriggerclientontheBroker,butdoesnotcreateanysubscriptions.The IntegrationServercreatesthesubscriptionswhenyousynchronize(push)the publishabledocumenttypewiththeBroker. Youcanalsousethepub.trigger:createTriggerservicetocreateatrigger.Formore informationaboutthisservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Creating a Filter for a Document


Youcanfurtherrefineaconditionbycreatingfiltersforthepublishabledocumenttypes. Afilterspecifiescriteriaforthecontentsofapublisheddocument.Forexample,suppose thatthedocumentEmployeeInformationcontainsapersonsageandstateofresidence.The firstfieldinthedocumentisanintegernamedageandthesecondfieldisaStringnamed state.Thefollowingfilterwillmatchonlythosedocumentswherethevalueofageis greaterthan65andthevalueofstateisequaltoFL.
%age% > 65 and %state% L_EQUALS "FL"

BoththeBrokerandIntegrationServerevaluateadocumentagainstasubscriptionsfilter uponreceivingthedocument.TheBrokerevaluatesthefiltertodeterminewhetherthe receiveddocumentmeetsthefiltercriteria.Ifthedocumentmeetsthefiltercriteria,the Brokerwillplacethedocumentinthesubscribersclientqueue.Ifthedocumentdoesnot meetthecriteriaspecifiedinthefilter,theBrokerdiscardsthedocument. AfterIntegrationServerreceivesadocumentanddeterminesthatthedocumenttype matchesatriggercondition,itappliesthefiltertothedocument.Ifthedocumentmeets thefiltercriteria,IntegrationServerexecutesthetriggerservicespecifiedinthetrigger condition.Ifthedocumentdoesnotmeetthefiltercriteria,theIntegrationServerdiscards thedocument.IntegrationServeralsocreatesajournallogentrystating:
No condition matches in trigger triggerName for document documentTypeName with activation activationID.

FilterscanbesavedwiththesubscriptionontheBrokerandwiththetriggeronthe IntegrationServer.Thelocationofthefilterdependsonthefilterssyntax,whichis evaluatedatdesigntime.Formoreinformationaboutfilterevaluationatdesigntimeand runtime,seeFilterEvaluationatDesignTimebelow.

Publish-Subscribe Developers Guide Version 7.1

121

7. Working with Triggers

Filter Evaluation at Design Time


Whenyousaveatrigger,IntegrationServerandtheBrokerevaluatethefilter.Integration Serverevaluatesthefiltertomakesureitusesthepropersyntax.Ifthesyntaxiscorrect, IntegrationServersavesthetriggerinanenabledstate.Ifthesyntaxisincorrect, IntegrationServersavesthetriggerinadisabledstate.Formoreinformationaboutthe syntaxforfilters,seetheConditionalExpressionsappendixinthewebMethodsDeveloper UsersGuide. TheBrokeralsoevaluatesthefiltersyntaxwhenitcreatessubscriptionstothepublishable documenttypesspecifiedinthetriggerconditions.Somefiltersthatarevalidonthe IntegrationServerarenotvalidontheBroker.Forexample,theBrokerprohibitstheuseof certainwordsorcharactersinfieldnames,suchasJavakeywords,@,*,andnames containingwhitespaces.IftheBrokerdeterminesthatthesyntaxisvalidfortheBroker,it savesthefilterwiththesubscription.IftheBrokerdeterminesthatthefiltersyntaxisnot validontheBrokerorifattemptingtosavethefilterontheBrokerwouldcauseanerror, theBrokersavesthesubscriptionwithoutthefilter.Thefilterwillbesavedonlyonthe IntegrationServer. Note: TheBrokersavesasmuchofafilteraspossiblewiththesubscription.Forexample, supposethatafilterconsistsofmorethanoneexpression,andonlyoneoftheexpressions containssyntaxtheBrokerconsidersinvalid.TheBrokersavestheexpressionsit considersvalidwiththesubscriptionontheBroker.(TheIntegrationServersavesallthe expressions.) Tip! YoucanusetheBrokerAdministratortoviewthefilterssavedwithasubscription. FormoreinformationaboutnamingconventionsandrestrictionsforBrokerelements,see NamingRulesforwebMethodsBrokerDocumentFieldsonpage 218.Formore informationaboutfiltersyntaxandtheBroker,seeConditionalExpressionsappendix inthewebMethodsDeveloperUsersGuide.

Filters and Performance


WhenafilterissavedonlyonIntegrationServerandnotontheBroker,theperformance ofIntegrationServercanbeaffected.WhentheBrokerappliesthefiltertoincoming documents,itdiscardsdocumentsthatdonotmeetfiltercriteria.TheBrokerneverplaces thedocumentinthesubscribersqueue.TheIntegrationServeronlyreceivesdocuments thatmeetthefiltercriteria. IfthesubscriptionfilterresidesonlyontheIntegrationServer,theBrokerautomatically placesthedocumentinthesubscribersqueue.TheBrokerdoesnotevaluatethefilterfor thedocument.TheBrokerroutesallofdocumentstothesubscriber,creatinggreater networktrafficbetweentheBrokerandtheIntegrationServerandrequiringmore processingbytheIntegrationServer.

Publish-Subscribe Developers Guide Version 7.1

122

7. Working with Triggers

YoucanusetheBrokerAdministratortoviewthefilterssavedwithasubscription.For moredetailsaboutsyntaxthatpreventsfiltersfrombeingsavedontheBroker,see ConditionalExpressionsappendixinthewebMethodsDeveloperUsersGuide.

Creating a Filter for a Publishable Document Type


Thefollowingproceduredescribeshowtocreateafilterforapublishabledocumenttype inatriggercondition. To specify a filter for a publishable document type in a trigger condition
T

1 2 3

IntheNavigationpanelofDeveloper,openthetrigger. Inthetophalfoftheeditor,selecttheconditioncontainingthepublishabledocument typetowhichyouwanttoapplythefilter. Inthelowerhalfoftheeditor,nexttothepublishabledocumenttypeforwhichyou wanttocreateafilter,enterthefilterintheFilterfield. TheIntegrationServerprovidessyntaxandoperatorsthatyoucanusetocreate expressionsforusewithfilters.Formoreinformation,seetheConditional ExpressionsappendixinthewebMethodsDeveloperUsersGuide.

OntheFilemenu,clickSavetosaveyourchangestothetrigger.TheIntegrationServer andBrokersavethefilterwiththesubscription.

Notes: IftheIntegrationServerisnotconnectedtoaBrokerwhenyousavethetrigger,the Brokerevaluatesthefilterthenexttimeyouenableandsavethetriggerafterthe connectionisreestablishedorwhenyousynchronizethedocumenttypesspecifiedin thetrigger. Ifyouneedtospecifynestedfieldsinthefilter,youcancopyapathtotheFilterfield fromthedocumenttype.Selectthefieldinthedocumenttype,rightclickandselect Copy.YoucanthenpasteintotheFilterfield.However,youmustadd%asapreface andsuffixtothecopiedpath. Ifmultipleconditionsinthetriggerspecifythesamepublishabledocumenttype,the filterappliedtothepublishabledocumenttypemustbethesameintheconditions.If thefiltersarenotthesame,theDeveloperdisplaysanerrormessagewhenyoutryto savethetrigger.

Using Multiple Conditions in a Trigger


Youcanbuildtriggersthatcancontainmorethanonecondition.Eachconditioncan associateoneormoredocumentswithaservice.Youcanusethesameserviceordifferent servicesforeachcondition.Youcancreateonlyonejoinconditioninatrigger,buta triggercancontainanynumberofsimpleconditions.

Publish-Subscribe Developers Guide Version 7.1

123

7. Working with Triggers

Whenatriggerreceivesadocument,theIntegrationServerdetermineswhichserviceto invokebyevaluatingthetriggerconditions.TheIntegrationServerevaluatesthetrigger conditionsinthesameorderinwhichtheconditionsappearintheeditor.Itispossible thatadocumentcouldsatisfymorethanoneconditioninatrigger.However,the IntegrationServerexecutesonlytheserviceassociatedwiththefirstsatisfiedcondition andignorestheremainingconditions.Therefore,theorderinwhichyoulistconditionson theeditorisimportant. Whenyoubuildatriggerwithmultipleconditions,eachconditioncanspecifythesame service.However,youshouldavoidcreatingconditionsthatspecifythesamepublishable documenttype.Iftheconditionsinatriggerspecifythesamepublishabledocumenttype, IntegrationServeralwaysexecutestheconditionthatappearsfirst.Forexample,ifa triggercontainedthefollowingconditions: Condition Name ConditionAB ConditionA Service serviceAB serviceA Document Types documentA or documentB documentA

IntegrationServerwillneverexecuteserviceA.WheneverIntegrationServerreceives documentA,thedocumentsatisfiesConditionAB,andIntegrationServerexecutesserviceAB.

Using Multiple Conditions for Ordered Service Execution


Youmightcreateatriggerwithmultipleconditionstohandleagroupofpublished documentsthatmustbeprocessedinaspecificorder.Foreachcondition,associateone publishabledocumenttypewithaservice.Placeyourconditionsintheorderinwhich youwanttheservicestoexecute.IntheProcessing modeproperty,specifyserialdocument processingsothatthetriggerwillprocessthedocumentsoneatatime,intheorderin whichtheyarereceived.Theserialdispatchingensuresthattheservicesthatprocessthe documentsdonotexecuteatthesametime.(Thisassumesthatthedocumentsare publishedandthereforereceivedintheproperorder.) Youmightwanttousemultipleconditionstocontroltheserviceexecutionwhenaservice thatprocessesadocumentdependsonanotherservicesuccessfullyexecuting.For example,toprocessapurchaseorder,youmightcreateoneservicethataddsanew customerrecordtoadatabase,anotherthataddsacustomerorder,andathirdthatbills thecustomer.Theservicethataddsacustomerordercanonlyexecutesuccessfullyifthe newcustomerrecordhasbeenaddedtothedatabase.Likewise,theservicethatbillsthe customercanonlyexecutesuccessfullyiftheorderhasbeenadded.Youcanensurethat theservicesexecuteinthenecessaryorderbycreatingatriggerthatcontainsone

Publish-Subscribe Developers Guide Version 7.1

124

7. Working with Triggers

conditionforeachexpectedpublishabledocumenttype.Youmightcreateatriggerwith thefollowingconditions: Condition Name Condition1 Condition2 Condition3 Service addCustomer addCustomerOrder billCustomer Document Type customerName customerOrder customerBill

Important! Anorderedscenarioassumesthatdocumentsarepublishedinthecorrectorder andthatyousetupthetriggertoprocessdocumentsserially.Formoreinformationabout buildingservicesthatpublishdocuments,seeChapter 6,PublishingDocuments.For moreinformationaboutspecifyingthedocumentprocessingforatrigger,seeSelecting MessagingProcessingonpage 133. Ifyoucreateonetriggerforeachoftheseconditions,youcouldnotguaranteethatthe IntegrationServerwouldinvokeservicesintherequiredorderevenifpublishing occurredinthatorder.Additionally,specifyingserialdispatchingforthetriggerensures thataservicewillfinishexecutingbeforethenextdocumentisprocessed.Forexample, theIntegrationServercouldstillbeexecutingaddCustomer,whenitreceivesthedocuments customerOrderandcustomerBill.Ifyouspecifiedconcurrentdispatchinginsteadofserial dispatching,theIntegrationServermightexecutetheservicesaddCustomerOrderand billCustomerbeforeitfinishedexecutingaddCustomer.Inthatcase,theaddCustomerOrderand billCustomerserviceswouldfail.

Adding Conditions to a Trigger


Triggerscancontainoneormoreconditions.Atriggercancontainmultiplesimple conditionsandamaximumofonejoincondition.Usethefollowingproceduretoadda conditiontoatrigger. To add a condition to a trigger 1 2 3 4 IntheNavigationpanel,openthetriggertowhichyouwanttoaddacondition. Inthetophalfoftheeditor,click toaddacondition.Developerautomatically assignstheconditionadefaultname,suchasCondition2. Definetheconditionasdescribedinstep 6inTocreateatriggeronpage 118. OntheFilemenu,clickSavetosavethetrigger. IftheIntegrationServerconsidersthetriggerinvalid,Developerdisplaysamessage indicatingwhythetriggerisinvalidandgivesyoutheoptionofsavingthetriggerin adisabledstate.

Publish-Subscribe Developers Guide Version 7.1

125

7. Working with Triggers

Ordering Conditions in a Trigger


Theorderinwhichyoulistconditionsintheeditorisimportantbecauseitindicatesthe orderinwhichtheIntegrationServerevaluatestheconditionsatruntime.Whenthe IntegrationServerreceivesadocument,itinvokestheservicespecifiedinthefirst conditionthatissatisfiedbythedocument.Theremainingconditionsareignored. Usethefollowingproceduretochangetheorderofconditionsinatrigger. To change the order of a condition in a trigger 1 2 3 4 IntheNavigationpanel,openthetrigger. Inthetophalfoftheeditor,selecttheconditiontobemoved. Click or tomovetheconditionupordown.

OntheFilemenu,clickSavetosavethetrigger.

Setting Trigger Properties


Asthedeveloperofatrigger,youcanconfiguretheruntimepropertiesofthistrigger, suchasthetriggercapacityandrefilllevel,documentprocessingmode,atimeoutvalue forjoinconditions,andaretrylimitforinvokingthetriggerservice.Youcanalsousethe triggerpropertiestoenableordisableatrigger.Forinformationaboutconfiguring exactlyonceprocessingforatrigger,seeChapter 8,ExactlyOnceProcessing

Disabling and Enabling a Trigger


YoucanusetheEnabledpropertytodisableorenableatrigger.Whenyoudisablea trigger,theIntegrationServerdisconnectsthetriggerclientontheBroker.TheBroker removesthedocumentsubscriptionscreatedbythetriggerclient.TheBrokerdoesnot placepublisheddocumentsinclientqueuesfordisabledtriggers.Whenyouenablea disabledtrigger,theIntegrationServerconnectsthetriggerclienttotheBrokerandre establishesthedocumentsubscriptionsontheBroker. Note: Youcannotdisableatriggerduringtriggerserviceexecution.

To disable a trigger 1 2 IntheNavigationpanel,openthetriggeryouwanttodisable. InthePropertiespanel,underGeneral,settheEnabledpropertytoFalse.

Publish-Subscribe Developers Guide Version 7.1

126

7. Working with Triggers

OntheFilemenu,clickSavetosavethetriggerinadisabledstate. IntheNavigationpanel,Developerchangesthecolorofthetriggericontograyto indicatethatitisdisabled.

Tip! Youcanalsosuspenddocumentretrievalanddocumentprocessingforatrigger. Unlikedisablingatrigger,suspendingretrievalandprocessingdoesnotdestroytheclient queue.TheBrokercontinuestoenqueuedocumentsforsuspendedtriggers.However,the IntegrationServerdoesnotretrieveorprocessdocumentsforsuspendedtriggers.For moreinformationaboutsuspendingtriggers,seethewebMethodsIntegrationServer AdministratorsGuide.

To enable a trigger 1 2 3 IntheNavigationpanel,openthetriggeryouwanttoenable. InthePropertiespanel,underGeneral,settheEnabledpropertytoTrue. OntheFilemenu,clickSavetosavethetrigger. IftheIntegrationServerdeterminesthatatriggerisnotvalid,Developerpreventsyou fromsavingthetriggerinanenabledstate.DeveloperresetstheEnabledpropertyto False.

Disabling and Enabling Triggers in a Cluster


WhenatriggerexistsonmultipleIntegrationServersinacluster,thesubscriptions createdbythetriggerremainactiveevenifyoudisablethetriggerfromoneofthe IntegrationServers.ThisisbecausethetriggerclientontheBrokerisasharedclient.The clientbecomesdisconnectedwhenyoudisablethetriggeronalltheserversinthecluster. Evenwhenthesharedtriggerclientbecomesdisconnected,thesubscriptionsestablished bythetriggerclientremainactive.TheBrokercontinuestoplacedocumentsinthequeue forthetriggerclient.Whenyoureenablethetriggeronanyserverinthecluster,allthe queueddocumentsthatdidnotexpirewillbeprocessedbythecluster. TodisableatriggerinaclusterofIntegrationServers,disablethetriggeroneach IntegrationServerinthecluster,andthenmanuallyremovethedocumentsubscriptions createdbythetriggerfromtheBroker.Formoreinformationaboutdeletingdocument subscriptionsontheBroker,seethewebMethodsBrokerAdministratorsGuide. Important! Disablingtriggersinaclusterinaproductionenvironmentisnotrecommended. Ifyoumustmakethetriggerunavailable,deletethetriggerfromeachserverandthen deletethetriggerclientqueueontheBroker.Formoreinformationaboutdeletingtriggers inacluster,seeDeletingTriggersinaClusteronpage 150.

Publish-Subscribe Developers Guide Version 7.1

127

7. Working with Triggers

Setting a Join Time-out


Whenyoucreateajoincondition(aconditionwithtwoormorepublishabledocument types),youneedtospecifyajointimeout.AjointimeoutspecifieshowlongIntegration Serverwaitsfortheotherdocumentsinthejoincondition.IntegrationServerusesthejoin timeoutperiodtoavoiddeadlocksituations(suchaswaitingforadocumentthatnever arrives)andtoavoidduplicateserviceinvocation. IntegrationServerstartsthejointimeoutperiodwhenitpullsthefirstdocumentthat satisfiesthejoinconditionfromthetriggerqueue. Note: YouneedtospecifyajointimeoutonlywhenyourconditionisanAll (AND)orOnly one (XOR)jointype.YoudonotneedtospecifyajointimeoutforanAny (OR) join condition. Theimplicationsofajointimeoutaredifferentdependingonthejointype.

Join Time-outs for All (AND) Join Conditions


AjointimeoutforanAll (AND)joinconditionspecifieshowlongtheIntegrationServer waitsforallofthedocumentsspecifiedinthejoincondition. WhentheIntegrationServerpullsadocumentfromthetriggerqueue,itdetermines whichconditionthedocumentsatisfies.IfthedocumentsatisfiesanAll (AND)join condition,theIntegrationServermovesthedocumentfromthetriggerqueuetothe ISInternaldatabase.TheIntegrationServerassignsthedocumentastatusofpending. TheIntegrationServerthenwaitsfortheremainingdocumentsinthejoincondition.Only documentswiththesameactivationIDasthefirstreceiveddocumentwillsatisfythejoin condition. IftheIntegrationServerreceivesallofthedocumentsspecifiedinthejoincondition(and processesthedocumentsfromthetriggerqueue)beforethetimeoutperiodelapses,it executestheservicespecifiedinthecondition.IftheIntegrationServerdoesnotreceiveall ofthedocumentsbeforethetimeoutperiodelapses,theIntegrationServerremovesthe pendingdocumentsfromthedatabaseandgeneratesajournallogmessage. Whenthetimeoutperiodelapses,thenextdocumentinthetriggerqueuethatsatisfies theAll (AND)conditioncausesthetimeoutperiodtostartagain.TheIntegrationServer placesthedocumentinthedatabaseandassignsastatusofpendingevenifthe documenthasthesameactivationIDasanearlierdocumentthatsatisfiedthejoin condition.TheIntegrationServerthenwaitsfortheremainingdocumentsinthejoin condition. FormoreinformationaboutAll (AND)joinconditionsseeChapter 9,UnderstandingJoin Conditions.

Publish-Subscribe Developers Guide Version 7.1

128

7. Working with Triggers

Join Time-outs for Only One (XOR) Join Conditions


AjointimeoutforanOnly one (XOR)joinconditionspecifieshowlongtheIntegration Serverdiscardsinstancesoftheotherdocumentsinthecondition. WhentheIntegrationServerpullsthedocumentfromthetriggerqueue,itdetermines whichconditionthedocumentsatisfies.IfthatconditionisanOnly one (XOR)condition,the IntegrationServerexecutestheservicespecifiedinthecondition.Whenitpullsthe documentfromthetriggerqueue,theIntegrationServerstartsthetimeoutperiod.For thedurationofthetimeoutperiod,theIntegrationServerdiscardsanydocumentsofthe typespecifiedinthejoincondition.TheIntegrationServerdiscardsonlythosedocuments withsameactivationIDasthefirstdocument. Whenthetimeoutperiodelapses,thenextdocumentinthetriggerqueuethatsatisfies theOnly one (XOR)conditioncausesthetriggerservicetoexecuteandthetimeoutperiod tostartagain.TheIntegrationServerexecutestheserviceevenifthedocumenthasthe sameactivationIDasanearlierdocumentthatsatisfiedthejoincondition. TheIntegrationServergeneratesajournallogmessagewhenthetimeoutperiodelapses foranOnly one (XOR)condition.FormoreinformationaboutOnly one (XOR)joinconditions, seeChapter 9,UnderstandingJoinConditions.

Setting a Join Time-out


Whenconfiguringtriggerproperties,youcanspecifywhetherajoinconditiontimesout andifitdoes,whatthetimeoutperiodshouldbe.Thetimeoutperiodindicateshowlong theIntegrationServerwaitsforadditionaldocumentsafterreceivingthefirstdocument specifiedinthejoincondition. To set a join time-out 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttosetthejointimeout. InthePropertiespanel,underGeneral,nexttoJoin expires,selectoneofthefollowing: Select... True To... IndicatethattheIntegrationServerstopswaitingfortheother documentsinthejoinconditiononcethetimeoutperiodelapses. IntheExpire afterproperty,specifythelengthofthejointimeout period.Thedefaulttimeperiodis1day.

Publish-Subscribe Developers Guide Version 7.1

129

7. Working with Triggers

Select... False

To... Indicatethatthejoinconditiondoesnotexpire.TheIntegration Serverwaitsindefinitelyfortheadditionaldocumentsspecifiedin thejoincondition.SettheJoin expirespropertytoFalseonlyifyou areconfidentthatallofthedocumentswillbereceived. Important! Ajoinconditionispersistedacrossserverrestarts.To removeawaitingjoinconditionthatdoesnotexpire,disable,then reenableandsavethetrigger.Reenablingthetriggereffectively recreatesthetrigger.

OntheFilemenu,clickSavetosavethetrigger.

Specifying Trigger Queue Capacity and Refill Level


TheIntegrationServercontainsatriggerdocumentstoreinwhichitsavesdocuments waitingforprocessing.TheIntegrationServerassignseachtriggeraqueueinthetrigger documentstore.Adocumentremainsinthetriggerqueueuntiltheserverdetermines whichtriggerconditionthedocumentsatisfiesandthenexecutestheservicespecifiedin thatcondition. Youcandeterminethecapacityofeachtriggersqueueinthetriggerqueue.Thecapacity indicatesthemaximumnumberofdocumentsthattheIntegrationServercanstorefor thattrigger.YoucanalsospecifyarefillleveltoindicatewhentheIntegrationServer shouldretrievemoredocumentsforthetrigger. Thedifferencebetweenthecapacityandtherefillleveldeterminesuptohowmany documentstheIntegrationServerretrievesforthetriggerfromtheBroker.Forexample,if youassignthetriggerqueueacapacityof10andarefilllevelof4,theIntegrationServer initiallyretrieves10documentsforthetrigger.Whenonly4documentsremaintobe processedinthetriggerqueue,theIntegrationServerretrievesupto6moredocuments.If 6documentsarenotavailable,theIntegrationServerretrievesasmanyaspossible. ThecapacityandrefilllevelalsodeterminehowfrequentlytheIntegrationServer retrievesdocumentsforthetriggerandthecombinedsizeoftheretrieveddocuments, specifically: Thegreaterthedifferencebetweencapacityandrefilllevel,thelessfrequentlythe IntegrationServerretrievesdocumentsfromtheBroker.However,thecombinedsize oftheretrieveddocumentswillbelarger. Thesmallerthedifferencebetweencapacityandrefilllevel,themorefrequentlythe IntegrationServerretrievesdocuments.However,thecombinedsizeoftheretrieved documentswillbesmaller.

Publish-Subscribe Developers Guide Version 7.1

130

7. Working with Triggers

Whenyousetvaluesforcapacityandrefilllevel,youneedtobalancethefrequencyof documentretrievalwiththecombinedsizeoftheretrieveddocuments.Usethefollowing guidelinestosetvaluesforcapacityandrefilllevelforatriggerqueue. Ifthetriggersubscribestosmalldocuments,setahighcapacity.Then,setrefilllevelto be30%to40%ofthecapacity.TheIntegrationServerretrievesdocumentsforthis triggerlessfrequently,however,thesmallsizeofthedocumentsindicatesthatthe combinedsizeoftheretrieveddocumentswillbemanageable.Additionally,setting therefilllevelto30%to40%ensuresthatthetriggerqueuedoesnotemptybeforethe IntegrationServerretrievesmoredocuments.Thiscanimproveperformanceforhigh volumeandhighspeedprocessing. Ifthetriggersubscribestolargedocuments,setalowcapacity.Then,settherefilllevel tojustbelowslightlylessthanthecapacity.TheIntegrationServerretrieves documentsmorefrequently,however,thecombinedsizeoftheretrieveddocuments willbemanageableandwillnotoverwhelmtheIntegrationServer. Note: YoucanspecifywhetherIntegrationServershouldrejectdocumentspublished locally,usingthepub.publish:publishorpub.publish.publishAndWaitservices,whenthequeuefor thesubscribingtriggerisatmaximumcapacity.Formoreinformationaboutthisfeature, seethedescriptionforthewatt.server.publish.local.rejectOOSparameterinthe webMethodsIntegrationServerAdministratorsGuide.

To specify trigger queue capacity and refill level 1 2 3 IntheNavigationpanel,openthetriggerforwhichyouwanttospecifytriggerqueue capacity. InthePropertiespanel,underTrigger queue,intheCapacityproperty,typethe maximumnumberofdocumentsthatthetriggerqueuecancontain.Thedefaultis10. IntheRefill levelproperty,typethenumberofunprocesseddocumentsthatmust remaininthistriggerqueuebeforetheIntegrationServerretrievesmoredocuments forthequeuefromtheBroker.Thedefaultis4. TheRefill levelvaluemustbelessthanorequaltotheCapacityvalue. 4 OntheFilemenu,clickSavetosavethetrigger.

Note: Atruntime,ifretrievingandprocessingdocumentsconsumestoomuchmemoryor toomanyserverthreads,theserveradministratormightneedtotemporarilyreducethe capacityandrefilllevelsfortriggerqueues.Theserveradministratorcanusethe IntegrationServerAdministratortograduallydecreasethecapacityandrefilllevelsofall triggerqueues.TheserveradministratorcanalsousetheIntegrationServer AdministratortochangetheCapacityorRefill levelvaluesforatrigger.Formore information,seethewebMethodsIntegrationServerAdministratorsGuide.

Publish-Subscribe Developers Guide Version 7.1

131

7. Working with Triggers

Controlling Document Acknowledgements for a Trigger


Whenatriggerservicefinishesprocessingaguaranteeddocument,theIntegrationServer returnsanacknowledgementtotheBroker.Uponreceiptoftheacknowledgement,the sendingresourceremovesitscopyofthedocumentfromstorage.Bydefault,the IntegrationServerreturnsanacknowledgementforaguaranteeddocumentassoonasit finishesprocessingthedocument. Note: TheIntegrationServerreturnsacknowledgementsforguaranteeddocumentsonly. TheIntegrationServerdoesnotreturnacknowledgementsforvolatiledocuments. Youcanincreasethenumberofdocumentacknowledgementsreturnedatonetimeby changingthevalueoftheAcknowledgement Queue Sizeproperty.Theacknowledgement queueisaqueuethatcontainspendingacknowledgementsforguaranteeddocuments processedbythetrigger.Whentheacknowledgementqueuesizeisgreaterthanone,a serverthreadplacesandocumentacknowledgementintotheacknowledgementqueue afteritfinishesexecutingthetriggerservice.Acknowledgementscollectinthequeueuntil abackgroundthreadreturnsthemasagrouptothesendingresource. IftheAcknowledgement Queue Sizeissettoone,acknowledgementswillnotcollectinthe acknowledgementqueue.Instead,theIntegrationServerreturnsanacknowledgementto thesendingresourceimmediatelyafterthetriggerservicefinishesexecuting. TheIntegrationServermaintainstwoacknowledgementqueuesforatrigger.Thefirst queueisaninboundorfillingqueueinwhichacknowledgementsaccumulate.Thesecond queueisanoutboundoremptyingqueuethatcontainstheacknowledgementsthe backgroundthreadgathersandreturnstothesendingresource. ThevalueoftheAcknowledgement Queue Sizepropertydeterminesthemaximumnumberof pendingacknowledgementsineachqueue.Consequently,themaximumnumberof pendingacknowledgementsforatriggeristwicethevalueofthisproperty.Forexample, iftheAcknowledgement Queue Sizepropertyissetto10,thetriggercanhaveupto20 pendingdocumentacknowledgements(10acknowledgementsintheinboundqueueand 10acknowledgementsintheoutboundqueue). Iftheinboundandoutboundacknowledgementqueuesfilltocapacity,theIntegration Serverblocksanyserverthreadsthatattempttoaddanacknowledgementtothequeues. TheblockedthreadsresumeexecutiononlyaftertheIntegrationServeremptiesoneofthe queuesbyreturningthependingacknowledgementstothesendingresource.

Publish-Subscribe Developers Guide Version 7.1

132

7. Working with Triggers

Increasingthesizeofatriggersacknowledgementqueuecanprovidethefollowing benefits: Reduces network traffic.Returningacknowledgementsoneatatimeforeachguaranteed documentthatisprocessedcanresultinahighvolumeofnetworktraffic. ConfiguringthetriggersothattheIntegrationServerreturnsseveraldocument acknowledgementsatoncecanreducetheamountofnetworktraffic. Increases server thread availability.Ifthesizeoftheacknowledgementqueueissetto1 (thedefault),theIntegrationServerreleasestheserverthreadusedtoprocessthe documentonlyafterreturningtheacknowledgement.Ifthesizeofthe acknowledgementqueueisgreaterthan1,theIntegrationServerreleasestheserver threadusedtoprocessthedocumentimmediatelyafterthethreadplacesthe acknowledgementintotheacknowledgementqueue.Whenacknowledgements collectinthequeue,serverthreadscanbereturnedtothethreadpoolmorequickly. Ifaresourceorconnectionfailureoccursbeforeacknowledgementsaresentorprocessed, thetransportredeliversthepreviouslyprocessed,butunacknowledgeddocuments.The numberofdocumentsredeliveredtoatriggerdependsonthesizeofthetriggers acknowledgementqueue.Ifexactlyonceprocessingisconfiguredforthetrigger,the IntegrationServerdetectstheredelivereddocumentsasduplicatesanddiscardsthem withoutreprocessingthem.Formoreinformationaboutexactlyonceprocessing,see Chapter 8,ExactlyOnceProcessing. To set the size of the acknowledgement queue 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttospecifytriggerqueue capacity. InthePropertiespanel,underTrigger queue,intheAcknowledgement Queue Size property,typethemaximumnumberofpendingdocumentacknowledgementsfor thetrigger.Thevaluemustbegreaterthanzero.Thedefaultis1. OntheFilemenu,clickSavetosavethetrigger.

Selecting Messaging Processing


MessageprocessingdetermineshowtheIntegrationServerprocessesthedocumentsin thetriggerqueue.Youcanspecifyserialprocessingorconcurrentprocessing.

Serial Processing
Inserialprocessing,theIntegrationServerprocessesthedocumentsinthetriggerqueue oneaftertheother.TheIntegrationServerretrievesthefirstdocumentinthetrigger queue,determineswhichconditionthedocumentsatisfies,andexecutestheservice specifiedinthetriggercondition.TheIntegrationServerwaitsfortheservicetofinish executingbeforeretrievingthenextdocumentfromthetriggerqueue.

Publish-Subscribe Developers Guide Version 7.1

133

7. Working with Triggers

Inserialprocessing,theIntegrationServerprocessesdocumentsinthetriggerqueuein thesameorderinwhichitretrievesthedocumentsfromtheBroker.Thatis,serial documentprocessingmaintainspublicationorder.However,theIntegrationServer processesdocumentsinatriggerqueuewithserialdispatchingmoreslowlythanit processesdocumentsintriggerqueuewithconcurrentprocessing. Note: SerialdocumentprocessingisequivalenttotheSharedDocumentOrdermodeof PublisherontheBroker. Tip! Ifyourtriggercontainsmultipleconditionstohandleagroupofpublisheddocuments thatmustbeprocessedinaspecificorder,useserialprocessing. Serial Processing in Clustered Environments Inaclusteredenvironment,serialdocumentprocessingdetermineshowtheBroker distributesguaranteeddocumentstotheindividualserverswithinthecluster.Inacluster, theindividualIntegrationServers(clusternodes)sharethesameBrokerclient.Thatis,the serversactasasingleBrokerclientandsharethesametriggerclientqueuesand documentsubscriptions. Foreachtrigger,eachserverintheclustermaintainsatriggerqueueinmemory.This allowsmultipleserverstoprocessdocumentsforasingletrigger.TheBrokermanagesthe distributionofdocumentstotheindividualtriggersinthecluster.Forserialtriggers,the Brokerdistributesdocumentssothattheclusterprocessesguaranteeddocumentsfroma singlepublisherinthesameorderwhichthedocumentswerepublished. Toensurethataserialtriggerprocessesguaranteeddocumentsfromindividual publishersinpublicationorder,theBrokerdistributesdocumentsfromonepublishertoa singleserverinacluster.TheBrokercontinuesdistributingdocumentsfromthepublisher tothesameserveraslongastheservercontainsunacknowledgeddocumentsfromthat publisherinthetriggerqueue.Oncetheserveracknowledgesallofthedocumentsfrom thepublishertotheBroker,otherserversintheclustercanprocessfuturedocumentsfrom thepublisher. Forexample,supposethataclustercontainstwoservers:ServerXandServerZ.Eachof theseserverscontainsthetriggerprocessCustomerInfo.TheprocessCustomerInfotrigger specifiesserialdocumentprocessingwithacapacityof2andarefilllevelof1.Foreach publisher,theclustermustprocessdocumentsforthistriggerinthepublicationorder.In thisexample,theprocessCustomerInfotriggerclientqueueontheBrokercontainsdocuments fromPublisherA,PublisherB,andPublisherC.PublisherApublisheddocumentsA1and A2,PublisherBpublisheddocumentsB1, B2,andB3,andPublisherCpublisheddocuments C1 andC2.

Publish-Subscribe Developers Guide Version 7.1

134

7. Working with Triggers

Thefollowingillustrationandexplanationdescribehowserialdocumentprocessing worksinaaclusteredenvironment.
Serial processing in a cluster of Integration Servers
Broker A1 B1 B2 C1 C2 B3 A2 Server X

processCustomerInfo Trigger Queue

Server Z processCustomerInfo Trigger Queue

Server X Broker B2 B3 A2 processCustomerInfo Trigger Queue A1 B1

3 4

Server Z Broker B3 A2 processCustomerInfo Trigger Queue C1 C2

5 6

Step
1

Description ServerXretrievesthefirsttwodocumentsinthequeue(documentsA1andB1) tofillitsprocessCustomerInfotriggerqueuetocapacity.ServerXbegins processingdocument A1. ServerZretrievesthedocumentsC1andC2tofillitsprocessCustomerInfotrigger queuetocapacity.ServerZbeginsprocessingthedocumentC1. EventhoughdocumentB2isthenextdocumentinthequeue,theBrokerdoes notdistributedocumentB2 fromPublisherBtoServerZbecauseServerX containsunacknowledgeddocumentsfromPublisherB.

Publish-Subscribe Developers Guide Version 7.1

135

7. Working with Triggers

Step
3 4

Description ServerXfinishesprocessingdocumentA1andacknowledgesdocumentA1to theBroker. ServerXrequests1moredocumentfromtheBroker.(TheprocessCustomerInfo triggerhasrefilllevelof1.)TheBrokerdistributesdocumentB2from PublisherBtoServerX. ServerZfinishesprocessingdocumentC1andacknowledgesdocumentC1 to theBroker ServerZrequests1moredocumentfromtheBroker.TheBrokerdistributes documentA2 toServerZ. ServerZcanprocessadocumentfromPublisherAbecausetheotherserverin thecluster(ServerX)doesnothaveanyunacknowledgeddocumentsfrom PublisherA.EventhoughdocumentB3isthenextdocumentinthequeue,the BrokerdoesnotdistributedocumentB3 toServerZbecauseServerXcontains unacknowledgeddocumentsfromPublisherB.

5 6

Note: TheBrokerandIntegrationServersinaclustercannotensurethatserialtriggers processvolatiledocumentsfromthesamepublisherintheorderinwhichthedocuments werepublished. Note: Whendocumentsaredeliveredtothedefaultclientinacluster,theBrokerand IntegrationServerscannotensurethatdocumentsfromthesamepublisherareprocessed inpublicationorder.ThisisbecausetheIntegrationServeracknowledgesdocuments deliveredtothedefaultclientassoonastheyareretrievedfromtheBroker.

Concurrent Processing
Inconcurrentprocessing,IntegrationServerprocessesthedocumentsinthetriggerqueue inparallel.Thatis,IntegrationServerprocessesasmanydocumentsinthetriggerqueue asitcanatthesametime.TheIntegrationServerdoesnotwaitfortheservicespecifiedin thetriggerconditiontofinishexecutingbeforeitbeginsprocessingthenextdocumentin thetriggerqueue.YoucanspecifythemaximumnumberofdocumentstheIntegration Servercanprocessconcurrently. Concurrentprocessingprovidesfasterperformancethanserialprocessing.The IntegrationServerprocessthedocumentsinthetriggerqueuemorequicklybecausethe IntegrationServercanprocessmorethanonedocumentatatime.However,themore documentstheIntegrationServerprocessesconcurrently,themoreserverthreadsthe IntegrationServerdispatches,andthemorememorythedocumentprocessingconsumes.

Publish-Subscribe Developers Guide Version 7.1

136

7. Working with Triggers

Additionally,forconcurrenttriggers,theIntegrationServerdoesnotguaranteethat documentsareprocessedintheorderinwhichtheyarereceived. Note: ConcurrentdocumentprocessingisequivalenttotheSharedDocumentOrdermode ofNoneontheBroker.

Selecting Document Processing


Usethefollowingproceduretoselectserialorconcurrentdocumentprocessingfora trigger. To specify document processing 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttospecifydocument processing. InthePropertiespanel,nexttoProcessing mode,selectoneofthefollowing: Select... Serial Concurrent To... SpecifythatIntegrationServershouldprocessdocumentsinthe triggerqueueoneaftertheother. SpecifythatIntegrationServershouldprocessasmanydocuments inthetriggerqueueasitcanatonce. IntheMax execution threadsproperty,specifythemaximumnumber ofdocumentsthatIntegrationServercanprocessconcurrently. IntegrationServerusesoneserverthreadtoprocesseach documentinthetriggerqueue. 3 IfyouselectedserialprocessingandyouwantIntegrationServertosuspend documentprocessinganddocumentretrievalautomaticallywhenatriggerservice endswithanerror,underFatal error handling,selectTruefortheSuspend on Error property. Formoreinformationaboutfatalerrorhandling,seeConfiguringFatalError Handlingonpage 138. 4 OntheFilemenu,clickSavetosavethetrigger.

Note: IntegrationServerAdministratorcanbeusedtochangethenumberofconcurrent executionthreadsforatriggertemporarilyorpermanently.Formoreinformation,seethe webMethodsIntegrationServerAdministratorsGuide.

Publish-Subscribe Developers Guide Version 7.1

137

7. Working with Triggers

Changing Document Processing


Afteryouperformcapacityplanningandtestingforyourintegrationsolution,youmight wanttomodifytheprocessingmodeforatrigger.Keepthefollowingpointsinmind beforeyouchangetheprocessingmodeforatrigger: IfyoucreatedthetriggeronanIntegrationServerconnectedtoaconfiguredBroker, youcanonlychangetheprocessingmodeiftheIntegrationServeriscurrently connectedtotheBroker. Important! Anydocumentsthatexistedinthetriggerclientqueuebeforeyouchanged thedispatchingmodewillbelostbecausetheIntegrationServerrecreatesthe associatedtriggerclientqueueontheBroker. IfyouchangethedocumentprocessingmodewhentheIntegrationServerisnot connectedtotheconfiguredBroker,Developerdisplaysamessagestatingthatthe operationcannotbecompleted. IftheIntegrationServeronwhichyouaredevelopingtriggersdoesnothavea configuredBroker,youcanchangethedocumentprocessingmodeatanytime withoutriskingthelossofdocuments.

Configuring Fatal Error Handling


Ifatriggerprocessesdocumentsserially,youcanconfigurefatalerrorhandlingforthe trigger.Afatalerroroccurswhenthetriggerserviceendsbecauseofanexception.You canspecifythatIntegrationServersuspendthetriggerautomaticallyifafatalerroroccurs duringtriggerserviceexecution.Specifically,theIntegrationServersuspendsdocument retrievalanddocumentprocessingforthetriggeriftheassociatedtriggerserviceends becauseofanexception. WhentheIntegrationServersuspendsdocumentprocessinganddocumentretrievalfora trigger,theIntegrationServerwritesthefollowingmessagetothejournallog:
Serial trigger triggerName has been automatically suspended due to an exception.

Documentprocessinganddocumentretrievalremainsuspendeduntiloneofthe followingoccurs: Youspecificallyresumedocumentretrievalordocumentprocessingforthetrigger. YoucanresumedocumentretrievalanddocumentprocessingusingtheIntegration ServerAdministrator,builtinservices(pub.trigger:resumeProcessingor pub.trigger:resumeRetrieval),orbycallingmethodsintheJavaAPI

Publish-Subscribe Developers Guide Version 7.1

138

7. Working with Triggers

(com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setProcessingSuspended() and com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setRetrievalSuspended()). IntegrationServerrestarts,thetriggerisenabledordisabled(andthenreenabled), thepackagecontainingthetriggerreloads.(WhenIntegrationServersuspends documentretrievalanddocumentprocessingforatriggerbecauseofanerror, IntegrationServerconsidersthechangetobetemporary.Formoreinformationabout temporaryvs.permanentstatechangesfortriggers,seethewebMethodsIntegration ServerAdministratorsGuide.) Formoreinformationaboutresumingdocumentprocessinganddocumentretrieval,see thewebMethodsIntegrationServerAdministratorsGuideandthewebMethodsIntegration ServerBuiltInServicesReference. Note: IntegrationServerdoesnotautomaticallysuspendtriggersbecauseoftransient errorsthatoccurduringtriggerserviceexecution.Formoreinformationabouttransient errorhandling,seeConfiguringTransientErrorHandlingonpage 140. Automaticsuspensionofdocumentretrievalandprocessingcanbeespeciallyusefulfor serialtriggersthataredesignedtoprocessagroupofdocumentsinaparticularorder.If thetriggerserviceendsinerrorwhileprocessingthefirstdocument,youmightnotwant tothetriggertoproceedwithprocessingthesubsequentdocumentsinthegroup.If IntegrationServerautomaticallysuspendsdocumentprocessing,youhavean opportunitytodeterminewhythetriggerservicedidnotexecutesuccessfullyandthen resubmitthedocumentusingwebMethodsMonitor. Byautomaticallysuspendingdocumentretrievalaswell,IntegrationServerpreventsthe triggerfromretrievingmoredocuments.BecauseIntegrationServeralreadysuspended documentprocessing,newdocumentswouldjustsitinthetriggerqueue.IfIntegration ServerdoesnotretrievemoredocumentsforthetriggerandIntegrationServerisina cluster,thedocumentsmightbeprocessedmorequicklybyanotherIntegrationServerin thecluster. Note: Youcanconfigurefatalerrorhandlingforserialtriggersonly.

To configure fatal error handling 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttospecifydocument processing. InthePropertiespanel,underFatal error handling,settheSuspend on errorpropertyto TrueifyouwantIntegrationServertosuspenddocumentprocessinganddocument retrievalautomaticallywhenatriggerserviceendswithanerror.Otherwise,select False.ThedefaultisFalse. OntheFilemenu,clickSavetosavethetrigger.

Publish-Subscribe Developers Guide Version 7.1

139

7. Working with Triggers

Configuring Transient Error Handling


Whenbuildingatrigger,youcanspecifywhatactionIntegrationServertakeswhenthe triggerservicefailsbecauseofatransienterrorcausedbyaruntimeexception.Thatis, youcanspecifywhetherornotIntegrationServershouldretrythetrigger. Aruntimeexception(specifically,anISRuntimeException)occurswhenthetriggerservice catchesandwrapsatransienterrorandthenrethrowsitasanISRuntimeException.A transienterrorisanerrorthatarisesfromatemporaryconditionthatmightberesolvedor correctedquickly,suchastheunavailabilityofaresourceduetonetworkissuesorfailure toconnecttoadatabase.Becausetheconditionthatcausedthetriggerservicetofailis temporary,thetriggerservicemightexecutesuccessfullyiftheIntegrationServerwaits andthenreexecutestheservice. YoucanconfiguretransienterrorhandlingforatriggertoinstructIntegrationServerto waitanspecifiedtimeintervalandthenreexecuteatriggerserviceautomaticallywhen anISRuntimeExceptionoccurs.IntegrationServerreexecutesthetriggerserviceusingthe originalinputdocument.

Configuring Retry Behavior for Trigger Services


Whenyouconfiguretransienterrorhandlingforatrigger,youspecifythefollowingretry behavior: WhetherIntegrationServershouldretrytriggerservicesforthetrigger.Keepinmind thatatriggerservicecanretryonlyifitiscodedtothrowISRuntimeExceptions.For moreinformation,seeServiceRequirementsforRetryingaTriggerServiceon page 141. ThemaximumnumberofretryattemptsIntegrationServershouldmakeforeach triggerservice. Thetimeintervalbetweenretryattempts. Howtohandlearetryfailure.Thatis,youcanspecifywhatactionIntegrationServer takesifalltheretryattemptsaremadeandthetriggerservicestillfailsbecauseofan ISRuntimeException.Formoreinformationabouthandlingretryfailure,see HandlingRetryFailureonpage 141. Thefollowingsectionsprovidemoreinformationaboutcodingthetriggerservicefor throwingexceptions,determiningthebestoptionforhandlingretryfailure,and configuringtheretrypropertiesforatrigger.

Publish-Subscribe Developers Guide Version 7.1

140

7. Working with Triggers

Service Requirements for Retrying a Trigger Service


Tobeeligibleforretry,thetriggerservicemustdooneofthefollowingtocatchatransient errorandrethrowitasanISRuntimeException: Ifthetriggerserviceisaflowservice,thetriggerservicemustinvoke pub.flow:throwExceptionForRetry.Formoreinformationaboutthe pub.flow:throwExceptionForRetry,seethewebMethodsIntegrationServerBuiltInServices Reference.Formoreinformationaboutbuildingaservicethatthrowsanexceptionfor retry,seethewebMethodsDeveloperUsersGuide. IfthetriggerserviceiswritteninJava,theservicecanuse com.wm.app.b2b.server.ISRuntimeException().Formoreinformationabout constructingISRuntimeExceptionsinJavaservices,seethewebMethodsIntegration ServerJavaAPIReferenceforthecom.wm.app.b2b.server.ISRuntimeExceptionclass. Ifatransienterroroccursandthetriggerservicedoesnotusepub.flow:throwExceptionForRetry orISRuntimeException()tocatchtheerrorandthrowanISRuntimeException,thetrigger serviceendsinerror.IntegrationServerwillnotretrythetriggerservice. AdapterservicesbuiltonIntegrationServer6.0orlater,andbasedontheART framework,detectandpropagateexceptionsthatsignalaretryifatransienterroris detectedontheirbackendresource.Thisbehaviorallowsfortheautomaticretrywhen theservicefunctionsasatriggerservice. Note: IntegrationServerdoesnotretryatriggerservicethatfailsbecauseaservice exceptionoccurred.Aserviceexceptionindicatesthatthereissomethingfunctionally wrongwiththeservice.AservicecanthrowaserviceexceptionusingtheEXITstep.For moreinformationabouttheEXITstep,seethewebMethodsDeveloperUsersGuide.

Handling Retry Failure


RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Whenyou configureretryproperties,youcanspecifyoneofthefollowingactionstodeterminehow IntegrationServerhandlesretryfailureforatrigger. Throw exception.WhenIntegrationServerexhauststhemaximumnumberofretry attempts,IntegrationServertreatsthelasttriggerservicefailureasaserviceerror. Thisisthedefaultbehavior. Suspend and retry later.WhenIntegrationServerreachesthemaximumnumberofretry attempts,IntegrationServersuspendsthetriggerandthenretriesthetriggerservice atalatertime.

Publish-Subscribe Developers Guide Version 7.1

141

7. Working with Triggers

Thefollowingsectionsprovidemoreinformationabouteachretryfailurehandling option. Overview of Throw Exception ThefollowingtableprovidesanoverviewofhowIntegrationServerhandlesretryfailure whentheThrow exceptionoptionisselected. Step


1 2 3

Description IntegrationServermakesthefinalretryattemptandthetriggerservicefails becauseofanISRuntimeException. IntegrationServertreatsthelasttriggerservicefailureaaserviceexception. IntegrationServerrejectsthedocument. Ifthedocumentisguaranteed,theIntegrationServerreturnsan acknowledgementtotheBroker. Ifatriggerservicegeneratesauditdataonerrorandincludesacopyofthe inputpipelineintheauditlog,youcanusewebMethodsMonitortore invokethetriggerservicemanuallyatalatertime.Notethatwhenyouuse webMethodsMonitortoprocessthedocument,itisprocessedoutoforder. Thatis,thedocumentisnotprocessedinthesameorderinwhichitwas received(orpublished)becausethedocumentwasacknowledgedtoits transportwhentheretryfailureoccurred.

IntegrationServerprocessesthenextdocumentinthetriggerqueue.

Insummary,thedefaultretryfailurebehavior(Throw exception)allowsthetriggerto continuewithdocumentprocessingwhenretryfailureoccursforatriggerservice.You canconfigureauditlogginginsuchawaythatyoucanusewebMethodsMonitorto submitthedocumentatalatertime(ideally,aftertheconditionthatcausedthetransient errorhasbeenremedied).

Publish-Subscribe Developers Guide Version 7.1

142

7. Working with Triggers

Overview of Suspend and Retry Later ThefollowingtableprovidesmoreinformationabouthowtheSuspend and retry later optionworks. Step
1 2

Description IntegrationServermakesthefinalretryattemptandthetriggerservicefails becauseofanISRuntimeException. IntegrationServersuspendsdocumentprocessinganddocumentretrievalfor thetriggertemporarily. ThetriggerissuspendedonthisIntegrationServeronly.IftheIntegration Serverispartofacluster,otherserversintheclustercanretrieveandprocess documentsforthetrigger. Note: Thechangetothetriggerstateistemporary.Documentretrievaland documentprocessingwillresumeforthetriggerifIntegrationServerrestarts, thetriggerisenabledordisabled,orthepackagecontainingthetrigger reloads.Youcanalsoresumedocumentretrievalanddocumentprocessing manuallyusingIntegrationServerAdministratororbyinvokingthe pub.trigger:resumeRetrievalandpub.trigger:resumeProcessingpublicservices.

IntegrationServerrollsbackthedocumenttothetriggerdocumentstore. Thisindicatesthattherequiredresourcesarenotreadytoprocessthe documentandmakesthedocumentavailableforprocessingatalatertime. Forserialtriggers,italsoensuresthatthedocumentmaintainsitspositionat thetopoftriggerqueue. IntegrationServerschedulesandexecutesaresourcemonitoringservice.A resourcemonitoringserviceisaservicethatyoucreatetodeterminewhether theresourcesassociatedwithatriggerserviceareavailable.Aresource monitoringservicereturnsasingleoutputparameternamedisAvailable.

Publish-Subscribe Developers Guide Version 7.1

143

7. Working with Triggers

Step
5

Description Iftheresourcemonitoringserviceindicatesthattheresourcesareavailable (thatis,thevalueofisAvailableistrue),IntegrationServerresumesdocument retrievalanddocumentprocessingforthetrigger. Iftheresourcemonitoringserviceindicatesthattheresourcesarenot available(thatis,thevalueofisAvailableisfalse),IntegrationServerwaitsa shorttimeinterval(bydefault,60seconds)andthenreexecutestheresource monitoringservice.IntegrationServercontinuesexecutingtheresource monitoringserviceperiodicallyuntiltheserviceindicatestheresourcesare available. Tip! Youcanchangethefrequencyatwhichtheresourcemonitoringservice executesbymodifyingthevalueofthe watt.server.trigger.monitoringIntervalproperty.

AfterIntegrationServerresumesthetrigger,IntegrationServerpassesthe documenttothetrigger.Thetriggerandtriggerserviceprocessthedocument justastheywouldanydocumentinthetriggerqueue. Note: Atthispoint,theretrycountissetto0(zero).

Insummary,theSuspend and retry lateroptionprovidesawaytoresubmitthedocument programmatically.Italsopreventsthetriggerfromretrievingandprocessingother documentsuntilthecauseofthetransienterrorconditionhasbeenremedied.This preservesthepublishingorder,whichcanbeespeciallyimportantforserialtriggers.

Configuring Transient Error Handling Properties for a Trigger


Usethefollowingproceduretoconfiguretransienterrorhandlingandretrybehaviorfora trigger. To configure transient error handling for a a trigger 1 IntheNavigationpanel,openthetriggerforwhichyouwanttoconfigureretry behavior.

Publish-Subscribe Developers Guide Version 7.1

144

7. Working with Triggers

InthePropertiespanel,underTransient error handling,intheRetry untilproperty,select oneofthefollowing: Select... Max attempts reached To... SpecifythatIntegrationServerretriesthetriggerservicea limitednumberoftimes. IntheMax retry attemptsproperty,enterthemaximum numberoftimestheIntegrationServershouldattemptto reexecutethetriggerservice.Thedefaultis0retries. Successful SpecifythattheIntegrationServerretriesthetrigger serviceuntiltheserviceexecutestocompletion. Note: Ifatriggerisconfiguredtoretryuntilsuccessfuland atransienterrorconditionisneverremedied,atrigger serviceentersintoaninfiniteretrysituationinwhichit continuallyreexecutestheserviceatthespecifiedretry interval.Becauseyoucannotdisableatriggerduring triggerserviceexecutionandyoucannotshutdownthe serverduringtriggerserviceexecution,aninfiniteretry situationcancausetheIntegrationServertobecome unresponsivetoashutdownrequest.Forinformation aboutescapinganinfiniteretryloop,seeTriggerService RetriesandShutdownRequestsonpage 147.

IntheRetry interval property,specifythetimeperiodtheIntegrationServerwaits betweenretryattempts.Thedefaultis10seconds.

Publish-Subscribe Developers Guide Version 7.1

145

7. Working with Triggers

SettheOn retry failurepropertytooneofthefollowing: Select... Throw exception To... IndicatethatIntegrationServerthrowsaservice exceptionwhenthelastallowedretryattemptends becauseofanISRuntimeException. Thisisthedefault. FormoreinformationabouttheThrow exception option,seeOverviewofThrowExceptionon page 142. Suspend and retry later IndicatethatIntegrationServersuspendsthetrigger whenthelastallowedretryattemptendsbecauseof anISRuntimeException.IntegrationServerretriesthe triggerserviceatalatertime.Formoreinformation abouttheSuspend and retry lateroption,seeOverview ofSuspendandRetryLateronpage 143. Note: IfyouwantIntegrationServertosuspendthe triggerandretryitlater,youmustprovidearesource monitoringservicethatIntegrationServercan executetodeterminewhentoresumethetrigger.For moreinformationaboutbuildingresource monitoringservice,seeAppendix B,Buildinga ResourceMonitoringService.

IfyouselectedSuspend and retry later,thenintheResource monitoring serviceproperty specifytheservicethatIntegrationServershouldexecutetodeterminetheavailability ofresourcesassociatedwiththetriggerservice.Multipletriggerscanusethesame resourcemonitoringservice.Forinformationaboutbuildingaresourcemonitoring service,seeBuildingaResourceMonitoringServiceonpage 221. OntheFilemenu,clickSave.

Notes: Triggersandservicescanbothbeconfiguredtoretry.Whenatriggerinvokesaservice (thatis,theservicefunctionsasatriggerservice),theIntegrationServerusesthe triggerretrypropertiesinsteadoftheserviceretryproperties. WhenIntegrationServerretriesatriggerserviceandthetriggerserviceisconfigured togenerateauditdataonerror,IntegrationServeraddsanentrytotheauditlogfor eachfailedretryattempt.EachoftheseentrieswillhaveastatusofRetriedandan errormessageofNull.However,ifIntegrationServermakesthemaximumretry attemptsandthetriggerservicestillfails,thefinalauditlogentryfortheservicewill

Publish-Subscribe Developers Guide Version 7.1

146

7. Working with Triggers

haveastatusofFailedandwilldisplaytheactualerrormessage.Thisoccurs regardlessofwhichretryfailureoptionthetriggeruses. IntegrationServergeneratesthefollowingjournallogmessagebetweenretry attempts: [ISS.0014.0031V3]ServiceserviceNamefailedwithISRuntimeException.Retryxofy willbegininretryIntervalmilliseconds. Ifyoudonotconfigureserviceretryforatrigger,setthe Max retry attemptspropertyto 0.Thiscanimprovetheperformanceofservicesinvokedbythetrigger. Youcaninvokethepub.flow:getRetryCountservicewithinatriggerservicetodetermine thecurrentnumberofretryattemptsmadebytheIntegrationServerandthe maximumnumberofretryattemptsallowedforthetriggerservice.Formore informationaboutthepub.flow:getRetryCountservice,seethewebMethodsIntegration ServerBuiltInServicesReference.

Trigger Service Retries and Shutdown Requests


WhileIntegrationServerretriesatriggerservice,IntegrationServerignoresrequeststo shutdowntheserveruntilthetriggerserviceexecutessuccessfullyorallretryattempts aremade.ThisallowsIntegrationServertoprocessadocumenttocompletionbefore shuttingdown. Sometimes,however,youmightwantIntegrationServertoshutdownwithout completingallretriesfortriggerservices.IntegrationServerprovidesaserverparameter thatyoucanusetoindicatethatarequesttoshutdowntheIntegrationServershould interrupttheretryprocessfortriggerservices.The

Publish-Subscribe Developers Guide Version 7.1

147

7. Working with Triggers

watt.sever.trigger.interruptRetryOnShutdownparametercanbesettooneofthe

following: Set to...


false

To... IndicatethatIntegrationServershouldnotinterruptthetriggerserviceretry processtorespondtoashutdownrequest.TheIntegrationServershuts downonlyafteritmakesalltheretryattemptsorthetriggerserviceexecutes successfully.Thisisthedefaultvalue. Important! Ifwatt.server.trigger.interruptRetryOnShutdownissetto falseandatriggerissettoretryuntilsuccessful,atriggerservicecanenter intoaninfiniteretrysituation.Ifthetransienterrorconditionthatcausesthe retryisnotresolved,IntegrationServercontinuallyreexecutestheserviceat thespecifiedretryinterval.Becauseyoucannotdisableatriggerduring triggerserviceexecutionandyoucannotshutdowntheserverduringtrigger serviceexecution,aninfiniteretrysituationcancauseIntegrationServerto becomeunresponsivetoashutdownrequest.Toescapeaninfiniteretry situation,setthewatt.server.trigger.interruptRetryOnShutdown to true.Thechangetakeseffectimmediately.

true

IndicatethatIntegrationServershouldinterruptthetriggerserviceretry processifashutdownrequestoccurs.Specifically,aftertheshutdown requestoccurs,IntegrationServerwaitsforthecurrentserviceretryto complete.Ifthetriggerserviceneedstoberetriedagain(theserviceends becauseofanISRuntimeException),theIntegrationServerstopstheretry processandshutsdown.Uponrestart,thetransport(theBrokeror,fora localpublish,thetransientstore)redeliversthedocumenttothetriggerfor processing. Note: Ifthetriggerserviceretryprocessisinterruptedandthetransport redeliversthedocumenttothetrigger,thetransportincreasestheredelivery countforthedocument.Ifthetriggerisconfiguredtodetectduplicatesbut doesnotuseadocumenthistorydatabaseoradocumentresolverserviceto performduplicatedetection,IntegrationServerconsiderstheredelivered documenttobeInDoubtandwillnotprocessthedocument.Formore informationaboutduplicatedetectionandexactlyonceprocessing,see Chapter 8,ExactlyOnceProcessing.

Note: Whenyouchangethevalueofthe
watt.sever.trigger.interruptRetryOnShutdownparameter,thechangetakeseffect

immediately.

Publish-Subscribe Developers Guide Version 7.1

148

7. Working with Triggers

Modifying a Trigger
Afteryoucreateatrigger,youcanmodifyitbychangingorrenamingthecondition, specifyingdifferentpublishabledocumenttypes,specifyingdifferenttriggerservices,or changingtriggerproperties.Tomodifyatrigger,youneedtolockthetriggerandhave writeaccesstothetrigger. IfyourintegrationsolutionincludesaBroker,theBrokerneedstobeavailablewhen editingtriggers.EditingtriggerswhentheBrokerisunavailablecancausethetriggerand itsassociatedtriggerclientontheBrokertobecomeoutofsync.Donoteditanyofthe followingtriggercomponentswhentheconfiguredBrokerisnotavailable: Anypublishabledocumenttypesspecifiedinthetrigger.Thatis,donotchangethe subscriptionsestablishedbythetrigger. Anyfiltersspecifiedinthetrigger. Thetriggerstate(enabledordisabled). Thedocumentprocessingmode(serialorconcurrentprocessing). IfyoueditanyofthesetriggercomponentswhentheBrokerisunavailable,Developer displaysamessagestatingthatsavingyourchangeswillcausethetriggertobecomeout ofsyncwithitsassociatedBrokerclient.Ifyouwanttocontinue,youwillneedto synchronizethetriggerwithitsassociatedBrokerclientwhentheconnectiontothe Brokerbecomesavailable.Tosynchronize,useDevelopertodisablethetrigger,reenable thetrigger,andsave.ThiseffectivelyrecreatesthetriggerclientontheBroker. Important! OnceyousetupaclusterofIntegrationServers,avoideditinganyofthetriggers inthecluster.Youcaneditselectedtriggerproperties(capacity,refilllevel,maximumand executionthreads)usingtheIntegrationServerAdministratorandsynchronizethese changesacrossacluster.Donoteditanyothertriggerproperties.Formoreinformation abouteditingtriggerpropertiesusingtheIntegrationServerAdministrator,seethe webMethodsIntegrationServerAdministratorsGuide.

Deleting Triggers
Whenyoudeleteatrigger,IntegrationServerdeletesthedocumentstoreforthetrigger andtheBrokerdeletestheclientforthetrigger.TheBrokeralsodeletesthedocumenttype subscriptionsforthetrigger.

Publish-Subscribe Developers Guide Version 7.1

149

7. Working with Triggers

Todeleteatrigger,youmustlockitandhavewriteaccesstoit.SeethewebMethods DeveloperUsersGuideforinformationaboutlockingandaccesspermissions(ACLs). To delete a trigger 1 2 3 SelectthetriggerintheNavigationpanel. OntheEditmenu,clickDelete. IntheDeleteConfirmationdialogbox,clickOK.

Note: Youcanalsousethepub.trigger:deleteTriggerservicetodeleteatrigger.Formore informationaboutthisservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Deleting Triggers in a Cluster


WhenatriggerexistsonmultipleIntegrationServersinacluster,thesubscriptions createdbythetriggerremainactiveevenifyoudeletethetriggerfromoneofthe IntegrationServers.Whendeletingtriggersfromtheserversinacluster,theassociated triggerclientontheBrokerremainsconnectedtotheclusteruntilyoudeletethetriggeron alloftheservers.Ifyoudonotdeletethetriggeronalloftheservers,thetriggerclient remainsconnectedandtheBrokercontinuestoplacedocumentsinthetriggerclient queue. TodeleteatriggerfromaclusterofIntegrationServers,deletethetriggerfromeach IntegrationServerinthecluster,andthenmanuallydeletethetriggerclientqueueonthe Broker.

Testing Triggers
YoucantestatriggerusingtoolsprovidedinDeveloper.Testingthetriggerenablesyou tomakesuretheserviceexecutes,andthatthedatatypesfortheinputs,andthefilter,if any,arevalid.Whenyoutestatrigger,youtestitlocally;thatis,thereisnoBroker involvement.Additionally,thedocumentcontainingtheinputdataisnotroutedthrough thedispatcherandtriggerqueueaswithapublisheddocument. Note: Whenyoutestatriggerthatcontainsmultipleconditions,youmusttestthe conditionsoneatatime.Whenaconditionspecifiesmorethanonepublishabledocument type,theIntegrationServerdoesnotperformjoinprocessing.ThatistheIntegration ServerdoesnotassignanactivationIDtoeachdocument.TheIntegrationServerrunsthe servicedirectlywiththespecifieddocumentvaluesasinputs.

Publish-Subscribe Developers Guide Version 7.1

150

7. Working with Triggers

To test and debug a trigger 1 2 IntheNavigationpanelofDeveloper,openthetrigger. OntheTestmenu,clickRun. Note: Whenyoutestatriggerconditionforthefirsttime,anduntilyouselecttheDont show this againcheckbox,Developerdisplaysaninformationalmessageabout activationIDs.TheIntegrationServerusesactivationIDsatruntimefortriggersthat containjoinconditions.TheIntegrationServerdoesnotrequireactivationIDsfor testinganddebuggingatriggercondition.ForinformationaboutactivationIDs,see AbouttheActivationIDonpage 94. 3 4 5 Ifthetriggercontainsonlyoneconditionandonedocumenttype,skiptostep 7. Ifthetriggercontainsonlyoneconditionandmultipledocumenttypes,skiptostep 6. Ifthetriggercontainsmultipleconditions,intheRuntestfortriggerNamedialogbox, selecttheconditionthatyouwanttotestandclickOK.Youcanonlytestonecondition atatime. IntheInputfortriggerNamedialogbox,selectanydocumenttypelistedandclickEdit. IntheInputfortriggerNamedialogbox,entervalidvaluesforthefieldsdefinedinthe documenttypeandclickOK.TheIntegrationServervalidatesvaluesafteryouclick OKtotestthecondition,asdescribedinstep 9. IfthereareadditionaldocumenttypeslistedintheconditionandthejointypeisAll (AND),repeatstep 6andstep 7foreachadditionaldocumenttype.Youmustenter valuesforalldocumenttypesinanAll (AND) joinconditionbeforeyoucantestthe triggercondition;otherwise,Developerdisplaysanerrormessage.Joinconditionsof typeAny (OR)orOnly one (XOR)requireyoutoentervaluesforonlyonedocumenttype. ClickOKtotestthecondition. IftheIntegrationServerrunstheservicesuccessfully,Developerdisplaysthe resultsintheResultspanel. IfIntegrationServercannottesttheconditionsuccessfully,Developerdisplaysan errormessage.TestingmightfailiftheDevelopercannotmatchafilterstring,orif oneormorevaluesareinvalid.

6 7

Publish-Subscribe Developers Guide Version 7.1

151

7. Working with Triggers

Testing Join Conditions from Developer


Testingatriggerconditionenablesyoutovalidatetheservice,datatypesfortheinputs, andthefilter,ifany.However,ifatriggerconditionspecifiesajoin,theIntegrationServer doesnotvalidatethejoin.Forexample,theIntegrationServerdoesnotcheckthatall documentsspecifiedinanAll (And)joinarethereorthatadocumentspecifiedforanOnly One (XOR)joinwasnotalreadyreceivedwithinthetimeoutperiod. IfyouwanttotestajoinconditionbypublishingdocumentsfromDeveloper,youmust usethesameactivationIDforallthedocumentsspecifiedinthejoin,andyoumustusean activationIDthatyouhavenotalreadyusedforpreviousjoinconditiontesting. Asimplewaytotestajoinconditionistocreateaflowservicethatcallsapublishservice foreachofthedocumentsyouspecifyinthejoincondition.TheIntegrationServer automaticallyassignsanactivationIDandusesthatactivationIDforallthedocuments publishedinthesameservice.

Publish-Subscribe Developers Guide Version 7.1

152

Chapter 8. Exactly-Once Processing

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 What Is Document Processing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Publish-Subscribe Developers Guide Version 7.1

153

8. Exactly-Once Processing

Introduction
ThischapterexplainswhatexactlyonceprocessingiswithinthecontextoftheIntegration Server,howtheIntegrationServerperformsexactlyonceprocessing,andhowto configureexactlyonceprocessingforatrigger.

What Is Document Processing?


Withinthepublishandsubscribemodel,documentprocessingistheprocessofevaluating documentsagainsttriggerconditionsandexecutingtheappropriatetriggerservicestoact onthosedocuments.TheprocessingusedbytheIntegrationServerdependsonthe documentstoragetypeandthetriggersettings.TheIntegrationServeroffersthreetypes ofdocumentprocessing. At-least-once processingindicatesthatatriggerprocessesadocumentoneormore times.Thetriggermightprocessduplicatesofthedocument.TheIntegrationServer providesatleastonceprocessingforguaranteeddocuments. At-most-once processingindicatesthatatriggerprocessesadocumentonceornotatall. Oncethetriggerreceivesthedocument,processingisattemptedbutnotguaranteed. TheIntegrationServerprovidesatmostonceprocessingforvolatiledocuments (whichareneitherredeliverednoracknowledged).TheIntegrationServermight processmultipleinstancesofavolatiledocument,butonlyifthedocumentwas publishedmorethanonce. Exactly-once processingindicatesthatatriggerprocessesadocumentonceandonly once.Thetriggerdoesnotprocessduplicatesofthedocument.TheIntegrationServer providesexactlyonceprocessingforguaranteeddocumentsreceivedbytriggersfor whichexactlyoncepropertiesareconfigured. Atleastonceprocessingandexactlyonceprocessingaretypesofguaranteedprocessing. Inguaranteedprocessing,theIntegrationServerensuresthatthetriggerprocessesthe documentonceitarrivesinthetriggerqueue.Theserverprovidesguaranteedprocessing fordocumentswithaguaranteedstoragetype. Note: Guaranteeddocumentdeliveryandguaranteeddocumentprocessingarenotthe samething.Guaranteeddocumentdeliveryensuresthatadocument,oncepublished,is deliveredatleastoncetothesubscribingtriggers.Guaranteeddocumentprocessingensures thatatriggermakesoneormoreattemptstoprocessthedocument. ThefollowingsectionprovidesmoreinformationabouthowtheIntegrationServer ensuresexactlyonceprocessing.

Publish-Subscribe Developers Guide Version 7.1

154

8. Exactly-Once Processing

Overview of Exactly-Once Processing


WithinIntegrationServer,exactlyonceprocessingisafacilitythatensuresonetime processingofaguaranteeddocumentbyatrigger.IntegrationServerensuresexactlyonce processingbyperformingduplicatedetectionandbyprovidingtheabilitytoretrytrigger services. Duplicatedetectiondetermineswhetherthecurrentdocumentisacopyofonepreviously processedbythetrigger.DuplicatedocumentscanbeintroducedintothewebMethods systemwhen: Thepublishingclientpublishesthesamedocumentmorethanonce. Duringpublishingorretrievalofguaranteeddocuments,thesendingresourceloses connectivitytothedestinationresourcebeforereceivingapositiveacknowledgement forthedocument.Thesendingresourcewillredeliverthedocumentwhenthe connectionisrestored. Note: Exactlyonceprocessingandduplicatedetectionareperformedforguaranteed documentsonly. IntegrationServerusesduplicatedetectiontodeterminethedocumentsstatus.The documentstatuscanbeoneofthefollowing: New.Thedocumentisnewandhasnotbeenprocessedbythetrigger. Duplicate.Thedocumentisacopyofonealreadyprocessedthetrigger. In Doubt.IntegrationServercannotdeterminethestatusofthedocument.Thetrigger mayormaynothaveprocessedthedocumentbefore. Toresolvethedocumentstatus,IntegrationServerevaluates,inorder,oneormoreofthe following: Redelivery countindicateshowmanytimesthetransporthasredeliveredthedocument tothetrigger. Document history databasemaintainsarecordofallguaranteeddocumentsprocessed bytriggersforwhichexactlyonceprocessingisconfigured. Document resolver serviceisaservicecreatedbyausertodeterminethedocument status.Thedocumentresolverservicecanbeusedinsteadoforinadditiontothe documenthistorydatabase. ThestepstheIntegrationServerperformstodetermineadocumentsstatusdependonthe exactlyoncepropertiesconfiguredforthesubscribingtrigger.Formoreinformation aboutconfiguringexactlyonceproperties,seeConfiguringExactlyOnceProcessingon page 166.

Publish-Subscribe Developers Guide Version 7.1

155

8. Exactly-Once Processing

ThetablebelowsummarizestheprocessIntegrationServerfollowstodeterminea documentsstatusandtheactiontheservertakesforeachduplicatedetectionmethod.
1

Check Redelivery Count Whenthetriggerisconfiguredtodetectduplicates,IntegrationServerwill checkthedocumentsredeliverycounttodetermineifthetriggerprocessedthe documentbefore. Redelivery Count 0 Action Ifusingdocumenthistory,IntegrationServer proceedsto 2 tocheckthedocumenthistory database. Ifdocumenthistoryisnotused,IntegrationServer considersthedocumenttobeNEW.Integration Serverexecutesthetriggerservice. >0 Ifusingdocumenthistory,IntegrationServer proceedsto 2 tocheckthedocumenthistory database. Ifdocumenthistoryisnotused,IntegrationServer proceedsto 3 toexecutethedocumentresolver service. Ifneitherdocumenthistorynoradocumentresolver serviceareused,IntegrationServerconsidersthe documenttobeINDOUBT. 1(Undefined) Ifusingdocumenthistory,proceedto 2 tocheckthe documenthistorydatabase. Ifdocumenthistoryisnotused,proceedto 3 to executethedocumentresolverservice. Otherwise,documentisNEW.Executetriggerservice.

Publish-Subscribe Developers Guide Version 7.1

156

8. Exactly-Once Processing

Check Document History Ifadocumenthistorydatabaseisconfiguredandthetriggerusesittomaintaina recordofprocesseddocuments,IntegrationServerchecksforthedocuments UUIDinthedocumenthistorydatabase. UUID Exists? No. Yes. Processingcompleted. Yes. Processingstarted. Action DocumentisNEW.Executetriggerservice. DocumentisaDUPLICATE.Acknowledgedocument anddiscard. Ifprovided,proceedto 3 toinvokethedocument resolverservice.Otherwise,documentisINDOUBT.

Execute Document Resolver Service Ifadocumentresolverserviceisspecified,IntegrationServerexecutesthe documentresolverserviceassignedtothetrigger. Returned Status NEW DUPLICATE INDOUBT Action Executetriggerservice. Acknowledgedocumentanddiscard. Acknowledgeandlogdocument.

Note: TheIntegrationServersendsInDoubtdocumentstotheauditsubsystemfor logging.YoucanresubmitInDoubtdocumentsusingwebMethodsMonitor.The IntegrationServerdiscardsDuplicatedocuments.Duplicatedocumentscannotbe resubmitted.FormoreinformationaboutwebMethodsMonitor,seethewebMethods Monitordocumentation. Thefollowingsectionsprovidemoreinformationabouteachmethodofduplicate detection.

Redelivery Count
Theredeliverycountindicatesthenumberoftimesthetransport(theBrokeror,forlocal publishing,thetransientstore)hasredeliveredadocumenttothetrigger.Thetransport thatdeliversthedocumenttothetriggermaintainsthedocumentredeliverycount.The transportupdatestheredeliverycountimmediatelyafterthetriggerreceivesthe document.Aredeliverycountotherthanzeroindicatesthatthetriggermighthave receivedandprocessed(orpartiallyprocessed)thedocumentbefore. Forexample,supposethatyourintegrationsolutionconsistsofanIntegrationServerand aBroker.Whentheserverfirstretrievesthedocumentforthetrigger,thedocument

Publish-Subscribe Developers Guide Version 7.1

157

8. Exactly-Once Processing

redeliverycountiszero.Aftertheserverretrievesthedocument,theBrokerincrements theredeliverycountto1.Ifaresource(BrokerorIntegrationServer)shutsdownbefore thetriggerprocessesandacknowledgesthedocument,theBrokerwillredeliverthe documentwhentheconnectionisreestablished.Theredeliverycountof1indicatesthat theBrokerdeliveredthedocumenttothetriggeroncebefore. Thefollowingtableidentifiesthepossibleredeliverycountvaluesandthedocument statusassociatedwitheachvalue. A redelivery count of... 1 Indicates... Theresourcethatdeliveredthedocumentdoesnotmaintaina documentredeliverycount.Theredeliverycountisundefined. TheIntegrationServerusesavalueof1toindicatethatthe redeliverycountisabsent.Forexample,adocumentreceived fromaBrokerversion6.0or6.0.1doesnotcontainaredelivery count.(Brokersversion6.0.1andearlierdonotmaintain documentredeliverycounts.) Ifothermethodsofduplicatedetectionareconfiguredforthis trigger(documenthistorydatabaseordocumentresolver service),theIntegrationServerusesthesemethodsto determinethedocumentstatus.Ifnoothermethodsof duplicatedetectionareconfigured,theIntegrationServer assignsthedocumentastatusofNewandexecutesthetrigger service. 0 Thisismostlikelythefirsttimethetriggerreceivedthe document. Ifthetriggerusesadocumenthistorytoperformduplicate detection,IntegrationServerchecksthedocumenthistory databasetodeterminethedocumentstatus.Ifnoother methodsofduplicatedetectionareconfigured,theserver assignsthedocumentastatusofNewandexecutesthetrigger service.

Publish-Subscribe Developers Guide Version 7.1

158

8. Exactly-Once Processing

A redelivery count of... >0

Indicates... Thenumberoftimestheresourceredeliveredthedocumentto thetrigger.Thetriggermightormightnothaveprocessedthe documentbefore.Forexample,theservermighthaveshut downbeforeorduringprocessing.Or,theconnectionbetween IntegrationServerandBrokerwaslostbeforetheservercould acknowledgethedocument.Theredeliverycountdoesnot provideenoughinformationtodeterminewhetherthetrigger processedthedocumentbefore. Ifothermethodsofduplicatedetectionareconfiguredforthis trigger(documenthistorydatabaseordocumentresolver service),theIntegrationServerusesthesemethodsto determinethedocumentstatus.Ifnoothermethodsof duplicatedetectionareconfigured,theserverassignsthe documentastatusofInDoubt,acknowledgesthedocument, usestheauditsubsystemtologthedocument,andwritesa journallogentrystatingthatanInDoubtdocumentwas received.

IntegrationServerusesredeliverycounttodeterminedocumentstatuswheneveryou enableexactlyonceprocessingforatrigger.Thatis,settingtheDetect duplicatesproperty totrueindicatesredeliverycountwillbeusedaspartofduplicatedetection. Note: Youcanretrievearedeliverycountforadocumentatanypointduringtrigger serviceexecutionbyinvokingthepub.publish:getRedeliveryCountservice.Formore informationaboutthisservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Document History Database


Thedocumenthistorydatabasemaintainsahistoryoftheguaranteeddocuments processedbytriggers.IntegrationServeraddsanentrytothedocumenthistorydatabase whenatriggerservicebeginsexecutingandwhenitexecutestocompletion(whetherit endsinsuccessorfailure).Thedocumenthistorydatabasecontainsdocumentprocessing informationonlyfortriggersforwhichtheUse historypropertyissettotrue. Thedatabasesavesthefollowinginformationabouteachdocument: Trigger ID. Universallyuniqueidentifierforthetriggerprocessingthedocument. Document UUID. Universallyuniqueidentifierforthedocument.Thepublisheris responsibleforgeneratingandassigningthisnumber.(IntegrationServer automaticallyassignsaUUIDtoallthedocumentsthatitpublishes.)

Publish-Subscribe Developers Guide Version 7.1

159

8. Exactly-Once Processing

Processing Status. Indicateswhetherthetriggerserviceexecutedtocompletionoris stillprocessingthedocument.Anentryinthedocumenthistorydatabasehaseithera statusofprocessingorastatusofcompleted.IntegrationServeraddsanentry withaprocessingstatusimmediatelybeforeexecutingthetriggerservice.Whenthe triggerserviceexecutestocompletion,IntegrationServeraddsanentrywithastatus ofcompletedtothedocumenthistorydatabase. Time. Thetimethetriggerservicebeganexecuting.Thedocumenthistorydatabase usesthesametimestampforbothentriesitmakesforadocument.Thisallowsthe IntegrationServertoremovebothentriesforaspecificdocumentatthesametime. Todeterminewhetheradocumentisaduplicateofonealreadyprocessedbythetrigger, IntegrationServerchecksforthedocumentsUUIDinthedocumenthistorydatabase.The existenceorabsenceofthedocumentsUUIDcanindicatewhetherthedocumentisnew oraduplicate. If the UUID... Doesnotexist. Then Integration Server... AssignsthedocumentastatusofNewandexecutesthetrigger service.TheabsenceoftheUUIDindicatesthatthetriggerhas notprocessedthedocumentbefore. AssignsthedocumentastatusofDuplicate.Theexistenceofthe processingandcompletedentriesforthedocumentsUUID indicatethetriggerprocessedthedocumentsuccessfully already.TheIntegrationServeracknowledgesthedocument, discardsit,andwritesajournallogentryindicatingthata duplicatedocumentwasreceived. Cannotdeterminethestatusofthedocumentconclusively.The absenceofanentrywithacompletedstatusfortheUUID indicatesthatthetriggerservicestartedtoprocessthe document,butdidnotfinish.Thetriggerservicemightstillbe executingortheservermighthaveunexpectedlyshutdown duringserviceexecution. Ifadocumentresolverserviceisspecified,IntegrationServer invokesit.Ifadocumentresolverserviceisnotspecifiedforthis trigger,IntegrationServerassignsthedocumentastatusofIn Doubt,acknowledgesthedocument,usestheauditsubsystem tologthedocument,andwritesajournallogentrystatingthat anInDoubtdocumentwasreceived. Existsina completedentry only. DeterminesthedocumentisaDuplicate.Theexistenceofthe completedentryindicatesthetriggerprocessedthedocument successfullyalready.TheIntegrationServeracknowledgesthe document,discardsit,andwritesajournallogentryindicating thataDuplicatedocumentwasreceived.

Existsina processingentry andacompleted entry.

Existsina processingentry only.

Publish-Subscribe Developers Guide Version 7.1

160

8. Exactly-Once Processing

Note: TheserveralsoconsidersadocumenttobeInDoubtwhenthedocumentsUUID (or,intheabsenceofaUUIDthevalueoftrackIDoreventID)exceeds96characters.The IntegrationServerthenusesthedocumentresolverservice,ifprovided,todeterminethe statusofthedocument.FormoreinformationabouthowtheIntegrationServerhandlesa documentmissingaUUID,seeDocumentswithoutUUIDsonpage 162. Forinformationaboutconfiguringthedocumenthistorydatabase,refertothewebMethods InstallationGuide.

What Happens When the Document History Database Is Not Available?


IftheconnectiontothedocumenthistorydatabaseisdownwhenIntegrationServer attemptstoquerythedatabase,IntegrationServerchecksthevalueofthe watt.server.trigger.preprocess.suspendAndRetryOnErrorpropertyandthentakes oneofthefollowingactions: If the property is set to
true

Integration Server does the following... Ifthedocumenthistorydatabaseisproperlyconfigured, IntegrationServersuspendsthetriggerandschedulesa systemtaskthatexecutesaservicethatchecksforthe availabilityofthedocumenthistorydatabase.Integration Serverresumesthetriggerandreexecutesitwhentheservice indicatesthatthedocumenthistorydatabaseisavailable. Ifthedocumenthistorydatabaseisnotproperlyconfigured, IntegrationServersuspendsthetriggerbutdoesnotschedule asystemtasktocheckforthedatabasesavailabilityandwill notresumethetriggerautomatically.Youmustmanually resumeretrievalandprocessingforthetriggerafter configuringthedocumenthistorydatabaseproperly. Thedefaultvalueistrue.

false

Ifadocumentresolverserviceisspecified,IntegrationServer executesittodeterminethestatusofthedocument. Otherwise,IntegrationServerassignsthedocumentastatus ofInDoubt,acknowledgesthedocument,andusestheaudit subsystemtologthedocument.

Formoreinformationaboutthe
watt.server.trigger.preprocess.suspendAndRetryOnErrorproperty,seethe

webMethodsIntegrationServerAdministratorsGuide.

Publish-Subscribe Developers Guide Version 7.1

161

8. Exactly-Once Processing

Documents without UUIDs


TheUUIDistheuniversallyuniqueidentifierthatdistinguishesadocumentfromother documents.ThepublisherisresponsibleforassigningaUUIDtoadocument.However, someclientsmightnotassignaUUIDtoadocument.Forexample,the6.0.1versionof IntegrationServerdoesnotassignaUUIDwhenpublishingadocument. IntegrationServerrequirestheUUIDtocreateandfindentriesinthedocumenthistory database.Therefore,iftheserverreceivesadocumentthatdoesnothaveaUUID,it createsaUUIDusingoneofthefollowingvaluesfromthedocumentenvelope: IfthetrackIDfieldcontainsavalue,theserverusesthetrackIDvalueastheUUID. IfthetrackIDfieldisempty,theserverusestheeventIDastheUUID. ThemaximumlengthoftheUUIDfieldis96characters.IfthetrackID(oreventID)is greaterthan96characters,theserverdoesnotassignaUUIDandcannotconclusively determinethedocumentsstatus.Ifspecified,IntegrationServerexecutesthedocument resolverservicetodeterminethedocumentsstatus.Otherwise,theIntegrationServer logsthedocumentasInDoubt.

Managing the Size of the Document History Database


Tokeepthesizeofthedocumenthistorydatabasemanageable,IntegrationServer periodicallyremovesexpiredrowsfromthedatabase.Thelengthoftimethedocument historydatabasemaintainsinformationaboutaUUIDvariespertriggeranddependson thevalueofthetriggersHistory time to liveproperty. TheIntegrationServerprovidesascheduledservicethatremovesexpiredentriesfromthe database.Bydefault,thewm.server.dispatcher:deleteExpiredUUID serviceexecutesevery10 minutes.Youcanchangethefrequencywithwhichtheserviceexecutes.Forinformation abouteditingscheduledservices,seethewebMethodsIntegrationServerAdministratorsGuide. Note: Thewatt.server.idr.reaperIntervalpropertydeterminestheinitialexecution frequencyforthewm.server.dispatcher:deleteExpiredUUIDservice.AfteryoudefineaJDBC connectionpoolforIntegrationServertousetocommunicatewiththedocumenthistory database,changetheexecutionintervalbyeditingthescheduledservice. YoucanalsouseIntegrationServerAdministratortoclearexpireddocumenthistory entriesfromthedatabaseimmediately. To clear expired entries from the document history database 1 2 3 4 OpenIntegrationServerAdministrator. FromtheSettingsmenuintheNavigationpanel,clickResources. ClickExactly Once Statistics. ClickRemove Expired Document History Entries.

Publish-Subscribe Developers Guide Version 7.1

162

8. Exactly-Once Processing

Document Resolver Service


Thedocumentresolverserviceisaservicethatyoubuildtodeterminewhethera documentsstatusisNew,Duplicate,orInDoubt.IntegrationServerpassesthedocument resolverservicesomebasicinformationthattheservicewillusetodeterminedocument status,suchastheredeliverycount,thedocumentUUID,thetransportusedtoroutethe document,andtheactualdocument.Thedocumentresolverservicemustreturnoneof thefollowingforthedocumentstatus:New,InDoubt,orDuplicate. Byusingtheredeliverycountandthedocumenthistorydatabase,IntegrationServercan assignmostdocumentsastatusofNeworDuplicate.However,asmallwindowoftime existswherecheckingtheredeliverycountandthedocumenthistorydatabasedoesnot conclusivelydeterminewhetheratriggerprocessedadocumentbefore.Forexample: Ifaduplicatedocumentarrivesbeforethetriggerfinishesprocessingtheoriginal document,thedocumenthistorydatabasedoesnotyetcontainanentrythatindicates processingcompleted.IntegrationServerassignstheseconddocumentastatusofIn Doubt. IfIntegrationServerfailsbeforecompletingdocumentprocessing,thetransport redeliversthedocument.However,thedocumenthistorydatabasecontainsonlyan entrythatindicatesdocumentprocessingstarted.IntegrationServerassignsthe redelivereddocumentastatusofInDoubt. Youcanwriteadocumentresolverservicetodeterminethestatusofdocumentsreceived duringthesewindows.Howthedocumentresolverservicedeterminesthedocument statusisuptothedeveloperoftheservice.Ideally,thewriterofthedocumentresolver serviceunderstandsthesemanticsofalltheapplicationsinvolvedandcanusethe documenttodeterminethedocumentstatusconclusively.Ifprocessinganearliercopyof thedocumentleftsomeapplicationresourcesinanindeterminatestate,thedocument resolverservicecanalsoissuecompensatingtransactions. Ifprovided,thedocumentresolverserviceisthefinalmethodofduplicatedetection. Formoreinformationaboutbuildingadocumentresolverservice,seeBuildinga DocumentResolverServiceonpage 168.

Document Resolver Service and Exceptions


Atruntime,adocumentresolverservicemightendbecauseofanexception.How IntegrationServerproceedsdependsonthetypeofexceptionandthevalueofthe watt.server.trigger.preprocess.suspendAndRetryOnErrorproperty. IfthedocumentresolverserviceendswithanISRuntimeException,andthe watt.server.trigger.preprocess.suspendAndRetryOnErrorpropertyissetto true,IntegrationServersuspendsthetriggerandschedulesasystemtasktoexecute thetriggersresourcemonitoringservice(ifoneisspecified).IntegrationServer resumesthetriggerandretriestriggerexecutionwhentheresourcemonitoring serviceindicatesthattheresourcesusedbythetriggerareavailable.

Publish-Subscribe Developers Guide Version 7.1

163

8. Exactly-Once Processing

Ifaresourcemonitoringserviceisnotspecified,youwillneedtoresumethetrigger manually(viatheIntegrationServerAdministratororthepub.trigger:resumeProcessing andpub.trigger:resumeRetrievalservices).Formoreinformationaboutconfiguringa resourcemonitoringservice,seeAppendix B,BuildingaResourceMonitoring Service. IfthedocumentresolverserviceendswithanISRuntimeException,andthe watt.server.trigger.preprocess.suspendAndRetryOnErrorpropertyissetto false,IntegrationServerassignsthedocumentastatusofInDoubt,acknowledgesthe document,andusestheauditsubsystemtologthedocument. Ifthedocumentresolverserviceendswithanexceptionotherthanan ISRuntimeException,IntegrationServerassignsthedocumentastatusofInDoubt, acknowledgesthedocument,andusestheauditsubsystemtologthedocument.

Extenuating Circumstances for Exactly-Once Processing


AlthoughtheIntegrationServerprovidesrobustduplicatedetectioncapabilities,activity outsideofthescopeorcontrolofthesubscribingIntegrationServermightcauseatrigger toprocessadocumentmorethanonce.Alternatively,situationscanoccurwherethe IntegrationServermightdetermineadocumentisaduplicatewhenitisactuallyanew document. Forexample,inthefollowingsituationsatriggerwithexactlyonceprocessingconfigured mightprocessaduplicatedocument. IftheclientpublishesadocumenttwiceandassignsadifferentUUIDeachtime,the IntegrationServerdoesnotdetecttheseconddocumentasaduplicate.Becausethe documentshavedifferentUUIDs,theIntegrationServerprocessesbothdocuments. Ifthedocumentresolverserviceincorrectlydeterminesthestatusofadocumenttobe new(whenitis,infact,aduplicate),theserverprocessesthedocumentasecondtime. Ifaclientpublishesadocumenttwiceandthesecondpublishoccursaftertheserver removestheexpireddocumentUUIDentriesfromthedocumenthistorytable,the IntegrationServerdeterminestheseconddocumentisnewandprocessesit.Because theseconddocumentarrivesafterthefirstdocumentsentrieshavebeenremoved fromthedocumenthistorydatabase,theIntegrationServerdoesnotdetectthesecond documentasaduplicate. IfthetimedriftbetweenthecomputershostingaclusterofIntegrationServersis greaterthantheduplicatedetectionwindowforthetrigger,oneoftheIntegration Serversintheclustermightprocessaduplicatedocument.(Thesizeoftheduplicate detectionwindowisdeterminedbytheHistory time to livepropertyunderExactly Once.) Forexample,supposetheduplicatedetectionwindowis15minutesandthattheclock onthecomputerhostingoneIntegrationServerintheclusteris20minutesaheadof theclocksonthecomputershostingtheotherIntegrationServers.Atriggerononeof theslowerIntegrationServersprocessesadocumentat10:00GMT.TheIntegration

Publish-Subscribe Developers Guide Version 7.1

164

8. Exactly-Once Processing

Serveraddstwoentriestothedocumenthistorydatabase.Bothentriesusethesame timestampandbothentriesexpireat10:15GMT.However,thefastIntegration Serveris20minutesaheadoftheothersandmightreaptheentriesfromthe documenthistorydatabasebeforeoneoftheotherIntegrationServersinthecluster does.IfthefastIntegrationServerremovestheentriesbefore15minuteshaveelapsed andaduplicateofthedocumentarrives,theIntegrationServersintheclusterwill treatthedocumentasanewdocument. Note: Timedriftoccurswhenthecomputersthathosttheclusteredserversgradually developdifferentdate/timevalues.EveniftheIntegrationServerAdministrator synchronizesthecomputerdate/timewhenconfiguringthecluster,thetime maintainedbyeachcomputercangraduallydifferastimepasses.Toalleviatetime drift,synchronizetheclusternodetimesregularly. InsomecircumstancestheIntegrationServermightnotprocessanew,uniquedocument becauseduplicatedetectiondeterminesthedocumentisduplicate.Forexample: IfthepublishingclientassignstwodifferentdocumentsthesameUUID,the IntegrationServerdetectstheseconddocumentasaduplicateanddoesnotprocessit. Ifthedocumentresolverserviceincorrectlydeterminesthestatusofadocumenttobe duplicate(whenitis,infact,new),theserverdiscardsthedocumentwithout processingit. Important! Intheaboveexamples,theIntegrationServerfunctionscorrectlywhen determiningthedocumentstatus.However,factorsoutsideofthecontrolofthe IntegrationServercreatesituationsinwhichduplicatedocumentsareprocessedornew documentsaremarkedasduplicates.Thedesignersanddevelopersoftheintegration solutionneedtomakesurethatclientsproperlypublishdocuments,exactlyonce propertiesareoptimallyconfigured,andthatdocumentresolverservicescorrectly determineadocumentsstatus.

Exactly-Once Processing and Performance


Exactlyonceprocessingforatriggerconsumesserverresourcesandcanintroducelatency intodocumentprocessingbytriggers.Forexample,whentheIntegrationServer maintainsahistoryofguaranteeddocumentsprocessedbyatrigger,eachtriggerservice executioncausestwoinsertsintothedocumenthistorydatabase.Thisrequiresthe IntegrationServertoobtainaconnectionfromtheJDBCpool,traversethenetworkto accessthedatabase,andtheninsertentriesintothedatabase. Additionally,whentheredeliverycountcannotconclusivelydetermineadocuments status,theservermustobtainadatabaseconnectionfromtheJDBCpool,traversethe network,andquerythedatabasetodeterminewhetherthetriggerprocessedthe document.

Publish-Subscribe Developers Guide Version 7.1

165

8. Exactly-Once Processing

Ifqueryingthedocumenthistorydatabaseisinconclusiveoriftheserverdoesnot maintainadocumenthistoryforthetrigger,invocationofthedocumentresolverservice willalsoconsumeresources,includingaserverthreadandmemory. Themoreduplicatedetectionmethodsthatareconfiguredforatrigger,thehigherthe qualityofservice.However,eachduplicatedetectionmethodcanleadtoadecreasein performance. Ifatriggerdoesnotneedexactlyonceprocessing(forexample,thetriggerservicesimply requestsorretrievesdata),considerleavingexactlyonceprocessingdisabledforthe trigger.Additionally,insteadofconfiguringallthreeduplicatedetectionmethods, considerconfiguringonlyoneortwo.

Configuring Exactly-Once Processing


Configureexactlyonceprocessingforatriggerwhenyouwantthetriggertoprocess guaranteeddocumentsonceandonlyonce.Ifitisacceptableforatriggerserviceto processduplicatesofadocument,youshouldnotconfigureexactlyonceprocessingfor thetrigger. Toenableexactlyonceprocessing,youcanconfigureuptothreemethodsofduplicate detectionpertrigger:redeliverycount,documenthistorydatabase,andadocument resolverservice. Forexample,ifyouareconfidentthattheredeliverycountwillalwaysindicatethe documentstatusaccurately,youcansetDetect duplicatestotrueandleavetheother exactlyoncepropertiesdisabled.TheIntegrationServerwillthenuseonlytheredelivery counttodeterminewhetheradocumentisaduplicate. Ifatriggerhasatriggerservicethatperformsfinancialtransactionsorupdatesadatabase, youmightwanttoconfigureallthreemethodsofduplicatedetection.Inthedocument resolverservice,inadditiontodeterminingthedocumentstatus,youmightwantto executecompensatingtransactionstoreverseanyfinancialtransactionscommittedbefore documentprocessingstopped. Keepthefollowingpointsinmindwhenconfiguringexactlyonceprocessing: TheIntegrationServercanperformexactlyonceprocessingforguaranteed documentsonly. Youdonotneedtoconfigureallthreemethodsofduplicatedetection. IftheIntegrationServerconnectstoan6.0or6.0.1versionoftheBroker,youmustuse adocumenthistorydatabaseand/oradocumentresolverservicetoperformduplicate detection.EarlierversionsoftheBrokerdonotmaintainaredeliverycount.The IntegrationServerwillassigndocumentsreceivedfromtheseBrokersaredelivery countof1.Ifyoudonotenableanothermethodofduplicatedetection,the

Publish-Subscribe Developers Guide Version 7.1

166

8. Exactly-Once Processing

IntegrationServerassignsthedocumentaNewstatusandexecutesthetrigger service. Note: Onstartup,DeveloperqueriestheIntegrationServertodeterminetheBroker versiontowhichitisconnected.Ifanexceptionoccursduringthischeck,Developer assumestheBrokerdoesnottrackdocumentredeliverycounts. StandaloneIntegrationServerscannotshareadocumenthistorydatabase.Onlya clusterofIntegrationServerscan(andmust)shareadocumenthistorydatabase. MakesuretheduplicatedetectionwindowsetbytheHistory time to livepropertyis longenoughtocatchduplicatedocumentsbutdoesnotcausethedocumenthistory databasetoconsumetoomanyserverresources.Ifexternalapplicationsreliably publishdocumentsonce,youmightuseasmallerduplicatedetectionwindow.Ifthe externalapplicationsarepronetopublishingduplicatedocuments,considersettinga longerduplicatedetectionwindow. Ifyouintendtouseadocumenthistorydatabaseaspartofduplicatedetection,you mustfirstinstallthedocumenthistorydatabasecomponentandassociateitwitha JDBCconnectionpool.Forinstructions,seethewebMethodsInstallationGuide. To configure exactly-once processing for a trigger 1 2 3 IntheNavigationpanel,openthetriggerforwhichyouwanttoconfigureexactly onceprocessing. InthePropertiespanel,underExactly Once,settheDetect duplicatespropertytoTrue. Touseadocumenthistorydatabaseaspartofduplicatedetection,dothefollowing: a b SettheUse historypropertytoTrue. IntheHistory time to liveproperty,specifyhowlongthedocumenthistorydatabase maintainsanentryforadocumentprocessedbythistrigger.Thisvalue determinesthelengthoftheduplicatedetectionwindow.

4 5

TouseaservicethatyoucreatetoresolvethestatusofInDoubtdocuments,specify thatserviceintheDocument resolver serviceproperty. OntheFilemenu,clickSave.

Publish-Subscribe Developers Guide Version 7.1

167

8. Exactly-Once Processing

Disabling Exactly-Once Processing


Ifyoulaterdeterminethatexactlyonceprocessingisnotnecessaryforatrigger,youcan disableit.Whenyoudisableexactlyonceprocessing,theIntegrationServerprovidesat leastonceprocessingforallguaranteeddocumentsreceivedbythetrigger. To disable exactly-once processing for a trigger 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttoconfigureexactly onceprocessing. InthePropertiespanel,underExactly Once,settheDetect duplicatespropertytoFalse. Developerdisablestheremainingexactlyonceproperties. 3 OntheFilemenu,clickSave.

Building a Document Resolver Service


Adocumentresolverserviceisaservicethatyoucreatetoperformduplicatedetection. TheIntegrationServerusesthedocumentresolverserviceasthefinalmethodofduplicate detection. Thedocumentresolverservicemustdothefollowing: Usethepub.publish:documentResolverSpecastheservicesignature.TheIntegrationServer passesthedocumentresolverservicevaluesforeachofthevariablesdeclaredinthe inputsignature. ReturnastatusofNew,InDoubt,orDuplicate.TheIntegrationServerusesthestatus todeterminewhetherornottoprocessthedocument. Catchandhandleanyexceptionsthatmightoccur,includinganISRuntimeException. ForinformationabouthowIntegrationServerproceedswithduplicatedetection whenanexceptionoccurs,seeDocumentResolverServiceandExceptionson page 163.Forinformationaboutbuildingservicesthatthrowaretryexception,seethe webMethodsDeveloperUsersGuide. Determinehowfardocumentprocessingprogressed.Ifnecessary,thedocument resolverservicecanissuecompensatingtransactionstoreversetheeffectsofa partiallycompletedtransaction.

Publish-Subscribe Developers Guide Version 7.1

168

8. Exactly-Once Processing

Viewing Exactly-Once Processing Statistics


YoucanusetheIntegrationServerAdministratortoviewahistoryoftheInDoubtor Duplicatedocumentsreceivedbytriggers.TheIntegrationServerAdministratordisplays thename,UUID(universallyuniqueidentifier),andstatusfortheDuplicateorInDoubt documentsreceivedbytriggersforwhichexactlyonceprocessingisconfigured.
Exactly-Once Statistics

TheIntegrationServersavesexactlyoncestatisticsinmemory.Whentheserverrestarts, thestatisticswillberemovedfrommemory. Note: Theexactlyoncestatisticstablemightnotcompletelyreflectalltheduplicate documentsreceivedviathefollowingmethods:deliverytothedefaultclient,local publishing,andfroma6.0.1Broker.Ineachofthesecases,theIntegrationServersaves documentsinatriggerqueuelocatedondisk.Whenatriggerqueueisstoredondisk,the triggerqueuerejectsimmediatelyanydocumentsthatarecopiesofdocumentscurrently savedinthetriggerqueue.TheIntegrationServerdoesnotperformduplicatedetection forthesedocuments.Consequently,theexactlyoncestatisticstablewillnotlistduplicate documentsthatwererejectedbythetriggerqueue.

To view exactly-once processing statistics 1 2 3 StartwebMethodsIntegrationServerandopentheIntegrationServerAdministrator. UndertheSettingsmenuinthenavigationarea,clickResources. ClickExactly-Once Statistics.

Publish-Subscribe Developers Guide Version 7.1

169

8. Exactly-Once Processing

To clear exactly-once processing statistics 1 2 3 4 StartwebMethodsIntegrationServerandopentheIntegrationServerAdministrator. UndertheSettingsmenuinthenavigationarea,clickResources. ClickExactly-Once Statistics. ClickClear All Duplicate or In Doubt Document Statistics.

Publish-Subscribe Developers Guide Version 7.1

170

Chapter 9. Understanding Join Conditions

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Join Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Subscribe Path for Documents that Satisfy a Join Condition . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Join Conditions in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Publish-Subscribe Developers Guide Version 7.1

171

9. Understanding Join Conditions

Introduction
Joinconditionsareconditionsthatassociatetwoormoredocumenttypeswithasingle triggerservice.Typically,joinconditionsareusedtocombinedatapublishedbydifferent sourcesandprocessitwithoneservice.

Join Types
ThejointypethatyouspecifyforajoinconditiondetermineswhethertheIntegration Serverneedstoreceiveall,any,oronlyoneofthedocumentstoexecutethetrigger service.Thefollowingtabledescribesthejointypesthatyoucanspecifyforacondition. Join Type All (AND) Description TheIntegrationServerinvokestheassociatedtriggerservice whentheserverreceivesaninstanceofeachspecifiedpublishable documenttypewithinthejointimeoutperiod.Theinstance documentsmusthavethesameactivationID.Thisisthedefault jointype. Forexample,supposethatajoinconditionspecifiesdocument typesdocumentAanddocumentBanddocumentC.Instancesofallthe documenttypesmustbereceivedtosatisfythejoincondition. Additionally,alldocumentsmusthavethesameactivationIDand mustbereceivedbeforethespecifiedjointimeoutelapses. Any (OR) TheIntegrationServerinvokestheassociatedtriggerservice whenitreceivesaninstanceofanyoneofthespecified publishabledocumenttypes. Forexample,supposethatthejoinconditionspecifiesdocument typesdocumentAordocumentBordocumentC.Onlyoneofthese documentsisrequiredtosatisfythejoincondition.The IntegrationServerinvokestheassociatedtriggerserviceevery timeitreceivesadocumentoftypedocumentA,documentB,or documentC.TheactivationIDdoesnotmatter.Notimeoutis necessary.

Publish-Subscribe Developers Guide Version 7.1

172

9. Understanding Join Conditions

Join Type Only one (XOR)

Description TheIntegrationServerinvokestheassociatedtriggerservice whenitreceivesaninstanceofanyofthespecifieddocument types.Forthedurationofthejointimeoutperiod,theIntegration Serverdiscards(blocks)anyinstancesofthespecifiedpublishable documenttypeswiththesameactivationID. Forexample,supposethatthejoinconditionspecifiesdocument typesdocumentAordocumentBordocumentC.Onlyoneofthese documentsisrequiredtosatisfythejoincondition.Itdoesnot matterwhichone.TheIntegrationServerinvokestheassociated triggerserviceafteritreceivesaninstanceofoneofthespecified documenttypes.TheIntegrationServercontinuestodiscard instancesofanyqualifieddocumenttypeswiththesame activationIDuntilthespecifiedjointimeoutelapses. Tip! YoucancreateanOnly one (XOR)joinconditionthatspecifies onlyonepublishabledocumenttype.Forexample,youcancreate aconditionthatspecifieddocumentAanddocumentA.Thiscondition indicatesthattheIntegrationServershouldprocessoneandonly onedocumentAwithaparticularactivationIDduringthejointime outperiod.TheIntegrationServerdiscardsanyotherdocumentA documentswiththesameactivationIDasthefirstonereceived.

Subscribe Path for Documents that Satisfy a Join Condition


TheIntegrationServerprocessesdocumentsthatsatisfyjoinconditionsinalmostthe samewayinwhichitprocessesdocumentsforsimpleconditions.WhentheIntegration ServerdeterminesthatadocumentsatisfiesanAll (AND)joinconditionoranOnly one (XOR) joincondition,itusesajoinmanagerandtheISInternaldatabasetoprocessandstorethe individualdocumentsinthejoincondition. ThefollowingsectionsprovidemoreinformationabouthowtheIntegrationServer processesdocumentsforjoinconditions. Note: TheIntegrationServerprocessesdocumentsthatsatisfyanAny (OR)conditioninthe samewaythatitprocessesdocumentsthatsatisfysimpleconditions.

Publish-Subscribe Developers Guide Version 7.1

173

9. Understanding Join Conditions

The Subscribe Path for Documents that Satisfy an All (AND) Join Condition
WhentheIntegrationServerreceivesadocumentthatsatisfiesanAll (AND)joincondition, itstoresthedocumentandthenwaitsfortheremainingdocumentsspecifiedinthejoin condition.TheIntegrationServerinvokesthetriggerserviceifeachofthefollowing occurs: Thetriggerreceivesaninstanceofeachdocumentspecifiedinthejoincondition ThedocumentshavethesameactivationID. Thedocumentsarrivewithinthespecifiedjointimeoutperiod. ThefollowingdiagramillustrateshowtheIntegrationServerreceivesandprocesses documentsforAll (AND)joinconditions.Inthefollowingexample,triggerXcontainsanAll (AND)joinconditionthatspecifiesthatdocumentAanddocumentBmustbereceivedforthe triggerservicetoexecute.
Subscribe path for documents that satisfy an All (AND) join condition
webMethods Broker Client Queue X webMethods Integration Server

1
Dispatcher

2
A B

3
A B

Cache Trigger Queue X

4
A Join Manager

5
A ISInternal Database

Guaranteed Storage

6
Trigger Document Store B

7
A B

Trigger Service X

8 9

Publish-Subscribe Developers Guide Version 7.1

174

9. Understanding Join Conditions

Step
1 2 3

Description ThedispatcherontheIntegrationServerusesaserverthreadtorequest documentsfromatriggersclientqueueontheBroker. Thethreadretrievesabatchofdocumentsforthetrigger,includingdocumentA anddocumentB.BothdocumentAanddocumentBhavethesameactivationID. ThedispatcherplacesdocumentAanddocumentBinthetriggersqueueinthe triggerdocumentstore.Thedispatcherthenreleasestheserverthreadusedto retrievethedocuments. Thedispatcherobtainsathreadfromtheserverthreadpool,pullsdocumentA fromthetriggerqueue,andevaluatesthedocumentagainsttheconditionsin thetrigger.TheIntegrationServerdeterminesthatdocumentApartiallysatisfies anAll (AND)joincondition.TheIntegrationServermovesdocumentAfromthe triggerqueuetothejoinmanager. TheIntegrationServerstartsthejointimeoutperiod. Note: Ifexactlyonceprocessingisconfiguredforthetrigger,theIntegration Serverfirstdetermineswhetherthedocumentisacopyofonealready processedbythetrigger.TheIntegrationServercontinuesprocessingthe documentonlyifthedocumentisnew.

ThejoinmanagersavesdocumentA totheISInternaldatabase.TheIntegration ServerassignsdocumentAastatusofpending.TheIntegrationServerreturns anacknowledgementforthedocumenttotheBrokerandreturnstheserver threadtotheserverthreadpool. Thedispatcherobtainsathreadfromtheserverthreadpool,pullsdocumentB fromthetriggerqueue,andevaluatesthedocumentagainsttheconditionsin thetrigger.TheIntegrationServerdeterminesthatdocumentBpartiallysatisfies anAll (AND)joincondition.TheIntegrationServersendsdocumentBfromthe triggerqueuetothejoinmanager. ThejoinmanagerdeterminesthatdocumentBhasthesameactivationIDas documentA.Becausethejointimeoutperiodhasnotelapsed,theAll (AND)join conditioniscompleted.Thejoinmanagerdeliversajoindocumentcontaining documentAanddocumentBtothetriggerservicespecifiedinthecondition. TheIntegrationServerexecutesthetriggerservice.

Publish-Subscribe Developers Guide Version 7.1

175

9. Understanding Join Conditions

Step
9

Description Afterthetriggerserviceexecutestocompletion(successorerror),oneofthe followingoccurs: IftheserviceexecutessuccessfullyanddocumentBisguaranteed,the IntegrationServeracknowledgesreceiptofdocumentBtotheBroker.The IntegrationServerthenremovesthecopyofthedocumentAfromthe databaseandremovesthecopyofdocumentBfromthetriggerqueue.The IntegrationServerreturnstheserverthreadtothethreadpool. Ifaserviceexceptionoccurs,theserviceendsinerrorandtheIntegration Serverrejectsthejoindocument.IfdocumentBisguaranteed,theIntegration ServeracknowledgesreceiptofdocumentBtotheBroker.TheIntegration ServerthenremovesthecopyofthedocumentAfromthedatabaseand removesthecopyofdocumentBfromthetriggerqueue.TheIntegration Serverreturnstheserverthreadtothethreadpoolandsendsanerror notificationdocumenttothepublisher. Ifthetriggerservicecatchesatransienterror,wrapsit,andrethrowsitas anISRuntimeException,thentheIntegrationServerwaitsforthelengthof theretryintervalandreexecutestheserviceusingtheoriginaldocument asinput.IftheIntegrationServerreachesthemaximumnumberofretries andthetriggerservicestillfailsbecauseofatransienterror,theIntegration Servertreatsthelastfailureasaserviceerror.Formoreinformationabout retryingatriggerservice,seeConfiguringTransientErrorHandlingon page 140. Note: Atransienterrorisanerrorthatarisesfromaconditionthatmightcorrect itselflater,suchasanetworkissueoraninabilitytoconnecttoadatabase.

Notes: Ifthejointimeoutperiodelapsesbeforetheotherdocumentsspecifiedinthejoin condition(inthiscase,documentB)arrive,thedatabasedropsdocumentA. IfdocumentBhadadifferentactivationID,thejoinmanagerwouldmovedocumentBto thedatabase,whereitwouldwaitforadocumentAwithamatchingactivationID. IfdocumentBarrivedafterthejointimeoutperiodstartedbythereceiptofdocumentA hadelapsed,documentBwouldnotcompletethejoincondition.Thedatabasewould havealreadydiscardeddocumentAwhenthejointimeoutperiodelapsed.Thejoin managerwouldsenddocumentB tothedatabaseandwaitforanotherdocumentAwith thesameactivationID.TheIntegrationServerwouldrestartthejointimeoutperiod. TheIntegrationServerreturnsacknowledgementsforguaranteeddocumentsonly.

Publish-Subscribe Developers Guide Version 7.1

176

9. Understanding Join Conditions

Ifatransienterroroccursduringdocumentretrievalorstorage,theauditsubsystem sendsthedocumenttotheloggingdatabaseandassignsitastatusofFAILED.You canusewebMethodsMonitortofindandresubmitdocumentswithaFAILEDstatus. FormoreinformationaboutusingwebMethodsMonitor,seethewebMethods Monitordocumentation. Ifatriggerservicegeneratesauditdataonerrorandincludesacopyoftheinput pipelineintheauditlog,youcanusewebMethodsMonitortoreinvokethetrigger serviceatalatertime.Formoreinformationaboutconfiguringservicestogenerate auditdata,seethewebMethodsDeveloperUsersGuide. Youcanconfigureatriggertosuspendandretryatalatertimeifretryfailureoccurs. RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Formore informationabouthandlingretryfailure,seeHandlingRetryFailureonpage 141.

The Subscribe Path for Documents that Satisfy an Only one (XOR) Join Condition
WhentheIntegrationServerreceivesadocumentthatsatisfiesanOnly one (XOR)condition, itexecutesthetriggerservicespecifiedinthejoincondition.Forthedurationofthejoin timeoutperiod,theIntegrationServerdiscardsdocumentsif: Thedocumentsareofthetypespecifiedinthejoincondition,and ThedocumentshavethesameactivationIDasthefirstdocumentthatsatisfiedthe joincondition. ThefollowingdiagramillustrateshowtheIntegrationServerreceivesandprocesses documentsforOnly one (XOR)joinconditions.Inthefollowingexample,triggerXcontains anOnly one (XOR)joinconditionthatspecifiesthateitherdocumentAordocumentBmustbe receivedforthetriggerservicetoexecute.TheIntegrationServeruseswhichever documentitreceivesfirsttoexecutetheservice.Whentheotherdocumentspecifiedinthe joinconditionarrives,theIntegrationServerdiscardsit.

Publish-Subscribe Developers Guide Version 7.1

177

9. Understanding Join Conditions

Subscribe path for documents that satisfy an Only one (XOR) condition
webMethods Broker Client Queue X webMethods Integration Server

1
Dispatcher

2
A B

3
A B

Memory Trigger Queue X

4
A Join Manager

5
A ISInternal Database

Guaranteed Storage

8
Trigger Document Store B

6
A

8
B (discarded)

Trigger Service X

Step
1 2 3

Description ThedispatcherontheIntegrationServerusesaserverthreadtorequest documentsfromthetriggersclientqueueontheBroker. Thethreadretrievesabatchofdocumentsforthetrigger,includingdocumentA anddocumentB.BothdocumentA anddocumentBhavethesameactivationID. ThedispatcherplacesdocumentAanddocumentBinthetriggersqueueinthe triggerdocumentstore.Thedispatcherthenreleasestheserverthreadusedto retrievethedocuments.

Publish-Subscribe Developers Guide Version 7.1

178

9. Understanding Join Conditions

Step
4

Description Thedispatcherobtainsathreadfromtheserverthreadpool,pullsdocumentA fromthetriggerqueue,andevaluatesthedocumentagainsttheconditionsin thetrigger.TheIntegrationServerdeterminesthatdocumentAsatisfiesanOnly one (XOR)joincondition.TheIntegrationServermovesdocumentAfromtrigger queuetothejoinmanager. TheIntegrationServerstartsthejointimeoutperiod. Note: Ifexactlyonceprocessingisconfiguredforthetrigger,theIntegration Serverfirstdetermineswhetherthedocumentisacopyofonealready processedbythetrigger.TheIntegrationServercontinuesprocessingthe documentonlyifthedocumentisnew.

5 6 7

ThejoinmanagersavesthestateofthejoinforthisactivationintheISInternal database. Thestateinformationincludesastatusofcomplete. TheIntegrationServercompletestheprocessingofdocumentAbyexecutingthe triggerservicespecifiedintheOnly one (XOR)condition. Afterthetriggerserviceexecutestocompletion(successorerror),oneofthe followingoccurs: Iftheserviceexecutessuccessfully,theIntegrationServerreturnsthe serverthreadtothethreadpool.IfthedocumentAisguaranteed,the IntegrationServerreturnsanacknowledgementtotheBroker.The IntegrationServerremovesthecopyofthedocumentfromthetrigger queueandreturnstheserverthreadtothethreadpool. Ifaserviceexceptionoccurs,theserviceendsinerrorandtheIntegration Serverrejectsthedocument.IfdocumentAisguaranteed,theIntegration ServerreturnsanacknowledgementtotheBroker.TheIntegrationServer removesthecopyofthedocumentfromthetriggerqueue,returnsthe serverthreadtothethreadpool,andsendsthepublisheranerror documenttoindicatethatanerrorhasoccurred. Ifthetriggerservicecatchesatransienterror,wrapsit,andrethrowsitas anISRuntimeException,theIntegrationServerwaitsforthelengthofthe retryintervalandreexecutestheservice.IftheIntegrationServerreaches themaximumnumberofretriesandthetriggerservicestillfailsbecauseof atransienterror,theIntegrationServertreatsthelastfailureasaservice error.Formoreinformationaboutretryingatriggerservice,see ConfiguringTransientErrorHandlingonpage 140. Note: Atransienterrorisanerrorthatarisesfromaconditionthatmightcorrect itselflater,suchasanetworkissueoraninabilitytoconnecttoadatabase.

Publish-Subscribe Developers Guide Version 7.1

179

9. Understanding Join Conditions

Step
8

Description Thedispatcherobtainsathreadfromtheserverthreadpool,pullsdocumentB fromthetriggerqueue,andevaluatesthedocumentagainsttheconditionsin thetrigger.TheIntegrationServerdeterminesthatdocumentBsatisfiestheOnly one (XOR)joincondition.TheIntegrationServersendsdocumentBfromthe triggerqueuetothejoinmanager. ThejoinmanagerdeterminesthatdocumentBhasthesameactivationIDas documentA.Becausethejointimeoutperiodhasnotelapsed,theIntegration ServerdiscardsdocumentB.TheIntegrationServerreturnsanacknowledgement fordocumentBtotheBroker.

Notes: IfdocumentBhadadifferentactivationID,thejoinmanagerwouldmovedocumentBto thedatabaseandexecutethetriggerservicespecifiedintheOnly one (XOR)join condition. IfdocumentBarrivedafterthejointimeoutperiodstartedbythereceiptofdocumentA hadelapsed,theIntegrationServerwouldinvokethetriggerservicespecifiedinthe Only one (XOR)joinconditionandstartanewtimeoutperiod. TheIntegrationServerreturnsacknowledgementsforguaranteeddocumentsonly. Ifatransienterroroccursduringdocumentretrievalorstorage,theauditsubsystem sendsthedocumenttotheloggingdatabaseandassignsitastatusofFAILED.You canusewebMethodsMonitortofindandresubmitdocumentswithaFAILEDstatus. FormoreinformationaboutusingwebMethodsMonitor,seethewebMethods Monitordocumentation. Ifatriggerservicegeneratesauditdataonerrorandincludesacopyoftheinput pipelineintheauditlog,youcanusewebMethodsMonitortoreinvokethetrigger serviceatalatertime.Formoreinformationaboutconfiguringservicestogenerate auditdata,seethewebMethodsDeveloperUsersGuide. Youcanconfigureatriggertosuspendandretryatalatertimeifretryfailureoccurs. RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Formore informationabouthandlingretryfailure,seeHandlingRetryFailureonpage 141.

Publish-Subscribe Developers Guide Version 7.1

180

9. Understanding Join Conditions

Join Conditions in Clusters


AclusteristreatedasanindividualIntegrationServerandactsassuchwiththeexception ofafailover.AnyIntegrationServerinaclustercanactastherecipientofadocumentthat fulfillsajoincondition.Ifthereismorethanonedocumentrequiredtofulfillthejoin,any membersoftheclustercanreceivethedocumentsaslongasthedocumentsarereceived withintheallocatedtimeoutperiod. Aclusterfailoveroccursifadocumentthatcompletesajoinconditionisreceivedbyan IntegrationServer,whichthenexperiencesahardwarefailure.Insuchcases,ifthe documentisguaranteed,theBrokerwillredeliverthedocumenttoanotherIntegration Serverwithintheclusterandthejoinconditionwillbefulfilled. Eachmemberofaclustersharesthesamedatabaseforstoringthejoinstate.

Publish-Subscribe Developers Guide Version 7.1

181

9. Understanding Join Conditions

Publish-Subscribe Developers Guide Version 7.1

182

Chapter 10. Synchronizing Data Between Multiple Resources

Data Synchronization Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Data Synchronization with webMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Tasks to Perform to Set Up Data Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Preparing the Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Defining How a Source Resource Sends Notification of a Data Change . . . . . . . . . . . . . . . . . 198 Defining the Structure of the Canonical Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Setting Up Key Cross-Referencing in the Source Integration Server . . . . . . . . . . . . . . . . . . . . 200 Setting Up Key Cross-Referencing in the Target Integration Server . . . . . . . . . . . . . . . . . . . . . 205 For N-Way Synchronizations Add Echo Suppression to Services . . . . . . . . . . . . . . . . . . . . . . 208

Publish-Subscribe Developers Guide Version 7.1

183

10. Synchronizing Data Between Multiple Resources

Data Synchronization Overview


Often,multipleapplicationswithinanenterpriseuseequivalentdata.Forexample,a CustomerRelationshipManagement(CRM)systemandaBillingsystembothcontain informationaboutcustomers.Iftheaddressforacustomerchanges,thechangeshouldbe updatedinbothsystems.Datasynchronizationkeepsequivalentdataacrossmultiple systemsconsistent;thatis,ifdataischangedinoneapplication,asimilarchangeismade totheequivalentdatainallotherapplications. Applicationscanbethoughtofasresourcesofdata.(Theremainderofthischapterwill refertoapplicationsasresources.)Therearetwomethodsforkeepingdatasynchronized betweenresources: Onewaysynchronization,inwhichoneresourceisthesourceofalldatachanges.When adatachangeisrequired,itisalwaysmadeinthesource.Afterachangeismade,itis propagatedtoallotherresources,whicharereferredtoasthetargets. Forexample,fordatasynchronizationbetweenaCRMsystem,Billingsystem,and OrderManagementsystem,theCRMmightbethesourceofallchangesandthe BillingandOrderManagementsystemsreceivechangesmadetotheCRMsystem. Nwaysynchronization,inwhicheveryresourcecanbeasourceandatargetaswell. Changestodatacanbemadeinanyresource.Afterthechangeismade,itis propagatedtoallotherresources. Forexample,fordatasynchronizationbetweenaCRMsystem,Billingsystem,and OrderManagementsystem,anyofthesystemscaninitiateachange,andthenthe changeispropagatedtotheothertwosystems. Nwaysynchronizationsaremorecomplexthanonewaysynchronizationsbecause multipleapplicationscanchangecorrespondingdataconcurrently.

Data Synchronization with webMethods


ToperformdatasynchronizationwithwebMethods,whenaresourcemakesadata change,itnotifiestheIntegrationServerbysendingadocumentthatdescribesthedata change.IfthesourceresourceisusingawebMethodsadapter,theadaptercansendan adapternotificationthatdescribesthedatachange. Thedatafromthesourceistypicallyinalayoutorstructurethatisnativetothesource. YousetupprocessingintheIntegrationServerthatmapsvaluesfromthenotification documenttobuildacommonstructuredocument,referredtoasacanonicaldocument. Eachtargetreceivesthecanonicaldocument,whichtheyusetoupdatetheequivalentdata ontheirsystems.

Publish-Subscribe Developers Guide Version 7.1

184

10. Synchronizing Data Between Multiple Resources

Thefollowingdiagramillustratesthebasicsofperformingdatasynchronizationwith webMethodssoftware.
Source Integration Server Target Integration Server
5
1

Adapter CRM System (Source Resource) Adapter Notification


2

Adapter Service Billing System (Target Resource) Adapter

Service
3

Broker

Service
4

Canonical Document

Step
1 2

Description Thesourceresourcemakesadatachange. TheIntegrationServerreceivesnotificationofthechangeonthesource.For example,intheaboveillustration,anadapterchecksforchangesonthesource. Whentheadapterrecognizesachangeonthesource,itsendsanadapter notificationthatcontainsinformationaboutthechangethatwasmade.The adaptermighteitherpublishtheadapternotificationordirectlyinvokea servicepassingittheadapternotification. Formoreinformationaboutadapternotifications,seetheguideforthespecific adapterthatyouareusingwithasourceresource.

Aservicethatyoucreatereceivesthenotificationofchangeonthesource.For example,itreceivestheadapternotification.Thisservicemapsdatafromthe changenotificationdocumenttoacanonicaldocument.Acanonicaldocumentis acommonbusinessdocumentthatcontainstheinformationthatalltarget resourceswillrequiretoincorporatedatachanges.Thecanonicaldocumenthas aneutralstructureamongtheresources.Formoreinformation,seeCanonical Documentsonpage 187. Afterformingthecanonicaldocument,theservicepublishesthecanonical document.Thetargetssubscribetothecanonicaldocument.

Publish-Subscribe Developers Guide Version 7.1

185

10. Synchronizing Data Between Multiple Resources

Step
4

Description Onatarget,thetriggerthatsubscribestothecanonicaldocumentinvokesa servicethatyoucreate.Thisservicemapsdatafromthecanonicaldocument intoadocumentthathasastructurethatisnativetothetargetresource.The targetresourceusestheinformationinthisdocumenttomaketheequivalent change. Thetargetresourcemakesadatachangethatisequivalenttothechangethat thesourceinitiated.Ifthetargetresourceisusinganadapter,anadapterservice canbeusedtomakethedatachange. Formoreinformationaboutadapterservices,seetheguideforthespecific adapterthatyouareusingwithatargetresource.

Equivalent Data and Native IDs


Asstatedabove,datasynchronizationkeepsequivalentdataacrossmultiplesystems consistent.Equivalentdatainresourcesdoesnotnecessarilyusethesamelayoutor structure.Thedatastructureisbasedontherequirementsoftheresource.Thefollowing exampleshowsdifferentdatastructuresforcustomerdatathataCRMsystemanda Billingsystemmightuse: Structure of customer data in a CRM system
Customer ID Customer Name First Surname Customer Address Line1 Line2 City State ZipCode Country Customer Payment Information Customer Account

Structure of customer data in a Billing system


Account ID Account Type Billing Account Owner Last First Billing Address Number Street AptNumber CityOrTown State Code Country Billing Preferences

Datainanapplicationcontainsakeyvaluethatuniquelyidentifiesanobjectwithinthe application.Intheexampleabove,thekeyvaluethatuniquelyidentifiesacustomer withintheCRMsystemistheCustomerID;similarly,thekeyvalueintheBillingsystemis theAccountID.Thekeyvalueinaspecificapplicationisreferredtoasthatapplications nativeID.Inotherwords,thenativeIDfortheCRMsystemistheCustomerID,andthe nativeIDfortheBillingsystemistheAccountID.

Publish-Subscribe Developers Guide Version 7.1

186

10. Synchronizing Data Between Multiple Resources

Canonical Documents
Sourceresourcessenddocumentstonotifyotherresourcesofdatachanges.Yousetup processingtomapthedatafromthesenotificationdocumentsintoacanonicaldocument. Acanonicaldocumentisadocumentwithaneutralstructure,anditencompassesall informationthatresourceswillrequiretoincorporatedatachanges.Useofcanonical documents: Simplifies data synchronization between multiple resourcesbyeliminatingtheneedfor everyresourcetounderstandthedocumentstructureofeveryotherresource. Resourcesneedonlyincludelogicformappingtoandfromthecanonicaldocument. Withoutacanonicaldocument,eachresourceneedstounderstandthedocument structuresoftheotherresources.Ifachangeismadetothedocumentstructureofone oftheresources,logicfordatasynchronizationwouldneedtochangeinallresources. Forexample,considerkeepingdatasynchronizedbetweenthreeresources:aCRM system,Billingsystem,andOrderManagementsystem.Becausethesystemsmap directlytoandfromeachothersnativestructures,achangeinoneresourcesstructure affectsallresources.IftheaddressstructurewaschangedfortheCRMsystem,you wouldneedtoupdatedatasynchronizationlogicinallresources.
Change data synchronization logic in the CRM system to move data from updated CRM fields into the equivalent fields of the Billing System document. Change data synchronization logic in the CRM system to move data from updated CRM fields into the equivalent fields of the Order Management System document.

CRM System

Change data synchronization logic in the Billing System to build the updated version of the CRM system document.

Billing System

Order Management System

Change data synchronization logic in the Order Management System to build the updated version of the CRM system document.

Whenyouuseacanonicaldocument,youlimitthenumberofdatasynchronization logicchangesthatyouneedtomake.Usingthesameexamplewheretheaddress structurechangesfortheCRMsystem,youwouldonlyneedtoupdatedata synchronizationlogicintheCRMsystem.


Change data synchronization logic in the CRM system to move data from updated CRM fields into the equivalent fields of the canonical document. CRM System

No change is needed to the Billing system because the format of the canonical document is not changed.

No change is needed to the Order Management system because the format of the canonical document is not changed. Billing System Order Management System

Publish-Subscribe Developers Guide Version 7.1

187

10. Synchronizing Data Between Multiple Resources

Makes adding new resources to the data synchronization easier.Withcanonicaldocuments, youonlyneedtoadddatasynchronizationlogictothenewresourcetousethe canonicaldocument.Withoutacanonicaldocument,youwouldneedtoupdatethe datasynchronizationlogicofallresourcessotheyunderstandthestructureofthe newlyaddedresource,andthenewresourcewouldneedtounderstandthe documentstructuresofalltheexistingresources.

Structure of Canonical Documents and Canonical IDs


Youdefinethestructureofthecanonicaldocumentstoincludeasupersetofallthefields thatarerequiredtokeepdatasynchronizedbetweentheresources.Formoreinformation, seeDefiningtheStructureoftheCanonicalDocumentonpage 199. Onefieldthatyoumustincludeinthestructureofthecanonicaldocumentisakeyvalue calledthecanonicalID.ThecanonicalIDuniquelyidentifiestheobjecttowhichthe canonicaldocumentrefers.Inotherwords,thecanonicalIDinacanonicaldocument servesthesamepurposethatthenativeIDdoesforanativedocumentfromoneofyour resources. Forexample,inaCRMsystemdocument,thenativeIDmightbeaCustomerIDthat uniquelyidentifiesacustomersaccountintheCRMsystem.Similarly,adocumentfrom theBillingsystemmightuseanAccountIDforthenativeIDtouniquelyidentifyan account.WhentheCRMsystemdocumentorBillingsystemdocumentsgetmappedtoa canonicaldocument,thedocumentmustcontainacanonicalIDthatuniquelyidentifies theobject(customeroraccount). TheIntegrationServerprovideskeycrossreferencingtoallowyoutocreateandmanagethe valuesofcanonicalIDsandtheirmappingstonativeIDs.Thekeycrossreferencingtools thattheIntegrationServerprovidesare: CrossreferencetablethatyouusetostorerelationshipsbetweencanonicalIDsand nativeIDs Builtinservicesthatyouusetomanipulatethecrossreferencetable. Formoreinformation,seeKeyCrossReferencingandtheCrossReferenceTablebelow.

Key Cross-Referencing and the Cross-Reference Table


Keycrossreferencingallowsyoutouseacommonkey(i.e.,thecanonicalID)tobuild relationshipsbetweenequivalentbusinessobjectsfromdifferentresources.Youbuildthe relationshipsbymappingkeyvalues(i.e.,thenativeIDs)fromtheresourcestoacommon canonicalID.Youmaintaintheserelationshipsinthecrossreferencetable. Note: Thefieldnameslistedinthetablebelowarenottheactualcolumnnamesforthe crossreferencetable.Theyaretheinputvariablenamesusedbythekeycrossreferencing builtinservicesthatcorrespondtothecolumnsofthecrossreferencetable.

Publish-Subscribe Developers Guide Version 7.1

188

10. Synchronizing Data Between Multiple Resources

Thecrossreferencetableincludesthefieldsdescribedinthefollowingtable: Fields appId objectId Description Astringthatcontainstheidentificationofaresource,forexample, CRMSystem.Youassignthisvalue. Astringthatcontainstheidentificationoftheoftheobjectthatyou wanttokeepsynchronized,forexample,Account.Youassign thisvalue. ThenativeIDoftheobjectforthespecificresourcespecifiedby appId.Youobtainthisvaluefromtheresource. ThecanonicalIDthatiscommontoallresourcesforidentifying thespecificobject.Youcanassignthisvalue,oryoucanallowa builtinservicetogeneratethevalueforyou.

nativeId canonicalKey

Forexample,tosynchronizedatabetweenaCRMsystem,Billingsystem,andOrder Managementsystem,youmighthavethefollowingrowsinthecrossreferencetable: appId CRMsystem Billingsystem OrderManagement objectId Account Account Account nativeId DAN0517 19970620 acct0104 canonicalKey WM6308 WM6308 WM6308

How the Cross-Reference Table Is Used for Key Cross-Referencing


Thefollowingdiagramillustrateshowtousethecrossreferencetableforkey crossreferencingduringdatasynchronization.

Publish-Subscribe Developers Guide Version 7.1

189

10. Synchronizing Data Between Multiple Resources

Cross-Reference Table appId Billing system CRM system Order Management objectId Account Account Account nativeId 19970620 DAN0517 acct0104 canonicalKey WM6308 WM6308 WM6308
2 3

Look up canonical ID WM6308 for appId Billing system and objectId Account to find native ID is 19970620. Billing System (Target Resource)

Look up the native ID DAN0517 for appId CRM system and objectId Account to find the canonical ID is WM6308. Native ID is DAN0517.
1

CRM System (Source Resource)

Order Management System (Target Resource)

Step
1

Description AsdescribedinDataSynchronizationwithwebMethodsonpage 184,whena sourcemakesadatachange,thesourcesendsadocumenttonotifyother resourcesofthechange.Aservicethatyoucreatereceivesthisdocument.Your servicebuildsthecanonicaldocumentthatdescribesthechange. Whenformingthecanonicaldocument,todeterminethevaluetouseforthe canonicalID,yourserviceinvokesabuiltinservice.Thisbuiltinservice inspectsthecrossreferencetabletolocatetherowthatcontainsthenativeID fromthesourcedocument.Thebuiltinservicethenreturnsthecorresponding canonicalIDfromthecrossreferencetable.Formoreinformationaboutthe builtinservicesyouuse,seeSettingUpKeyCrossReferencingintheSource IntegrationServeronpage 200. Aservicethatyoucreateonthetargetreceivesthecanonicaldocument.Whena targetreceivesthecanonicaldocument,itneedstodeterminethenativeIDof theobjectthatthechangeaffects.TodeterminethenativeID,yourserviceonthe targetinvokesabuiltinservice.Thisbuiltinserviceinspectsthecrossreference tabletolocatetherowthatcontainsthecanonicalIDandtheappropriate resourceidentifiedbytheappIdandobjectidentifiedbyobjectId.Thebuiltin servicethenreturnsthecorrespondingnativeIDfromthecrossreferencetable. Formoreinformationaboutthebuiltinservicesyouuse,seeSettingUpKey CrossReferencingintheTargetIntegrationServeronpage 205.

Publish-Subscribe Developers Guide Version 7.1

190

10. Synchronizing Data Between Multiple Resources

Echo Suppression for N-Way Synchronizations


OneotherfeaturethattheIntegrationServerprovidesfordatasynchronizationisecho suppression,whichisalsocalledlatching.Echosuppression(orlatching)istheprocessof preventingcircularupdatingfromoccurring.Circularupdatingcanoccurwhen performingnwaysynchronizations(datasynchronizationswhereeveryresourcecanbea sourceandatargetaswell). Circularupdatingoccurswhenthesourcesubscribestothecanonicaldocumentthatit publishesasillustratedinthediagrambelow.
1

Notification Update
3

Source Resource

Source Integration Server

Broker

Step
1 2 3

Description Adatachangeoccursonasource,andthesourceresourcesendsanotification document. ThesourceIntegrationServerbuildsandpublishesacanonicaldocument. Becausethesourceisalsoatarget,it(aswellasallothertargets)subscribesto thecanonicaldocumentviaatrigger.Asaresult,thesourcereceivesthe canonicaldocumentitjustpublished.LogiconthesourceIntegrationServer usesthecanonicaldocumenttobuildanupdatedocumenttosendtothesource. Thesourcereceivestheupdatedocumentandmakesthedatachangeagain. Becausethesourcemadethisdatachange,itonceagainactsasasourcetonotify targetsofthedatachange.Theprocessstartsagainwithstep1.

Inadditiontothesourceimmediatelyreceivingthecanonicalthatitformed,itcanalso receivethecanonicaldocumentmanymoretimesbecauseothertargetsbuildandpublish thecanonicaldocumentaftermakingthedatachangethatthesourceinitiated.Seebelow foranillustrationofthiscircularupdating.


1

Notification

Source Resource

Update
6

Source Integration Server

Broker

Target Integration Server


5

Update

Notification
4

Target Resource

Publish-Subscribe Developers Guide Version 7.1

191

10. Synchronizing Data Between Multiple Resources

Step
1 2 3 4 5 6

Description Adatachangeoccursonasource,andthesourcesendsanotificationdocument. ThesourceIntegrationServerbuildsandpublishesacanonicaldocument. Atargetreceivesthecanonicaldocumentandmakestheequivalentchange. Becausethetargetmadeadatachange,itsendsanotificationdocumentforthe datachange. ThetargetIntegrationServerbuildsandpublishesacanonicaldocument. Thesourcereceivesthenotificationofthechangethatwasmadebythetarget andmakesthechange,again.Thisresultsintheprocessstartingagainwith step 1.

Toavoidthecircularupdating,theIntegrationServerprovidesyouwiththefollowing toolstoperformechosuppression: TheisLatchClosedfieldinthecrossreferencetablethatyouusetokeeptrackof whetheraresourcehasalreadymadeadatachangeornot. BuiltinservicesthatyouusetomanipulatetheisLatchClosedfieldinthe crossreferencetableto: DeterminethevalueoftheisLatchClosedfield,and SetthevalueoftheisLatchClosedcolumn.

How the isLatchedClosed Field Is Used for Echo Suppression


InadditiontotheappID,objectId,nativeId,andcanonicalKeyfieldsthataredescribedin KeyCrossReferencingandtheCrossReferenceTableonpage 188,thecrossreference tablealsoincludestheisLatchClosedfield.TheisLatchClosefieldactsasaflagthat indicateswhetheranobjectmanagedbyaresource(e.g.,accountinformation)isallowed tobeupdatedorwhetheradatachangehasalreadybeenmadetotheobjectandtherefore shouldnotbemadeagain. When the isLatchClosed field is false,thisindicatesthatthelatchisopenandtherefore updatescanbemadetotheobject. When the isLatchClosed field is true,thisindicatesthatthelatchisclosedandtherefore updatesshouldnotbemadetotheobject.

Publish-Subscribe Developers Guide Version 7.1

192

10. Synchronizing Data Between Multiple Resources

ThefollowingdiagramillustrateshowtousetheisLatchClosedfieldforechosuppression duringdatasynchronization.
Notification Service latch is open Send notification. close latch appID CRM system isLatchClosed true
1

Update Service Update latch is open Make update. close latch appID Billing system isLatchClosed true
4

Notification CRM System (Source Resource)

Source Integration Server


3

Broker

Target Integration Server


6

Update Notification
5

Billing System (Target Resource)

Update Service latch is closed Do not update. re-open latch appID CRM system isLatchClosed false

Notification Service latch is closed Do not send notification. re-open latch appID Billing system isLatchClosed false

Step
1 2

Description Adatachangeoccursonasource,andthesourcesendsanotificationdocument. Anotificationservicethatyoucreatetonotifytargetsofadatachangeinvokesthe pub.synchronization.latch:isLatchClosed builtinservicetodeterminewhetherthelatch fortheobjectisopenorclosed.Initiallyforthesource,thelatchfortheobjectthat waschangedisopen.Thisindicatesthatupdatescanbemadetothisobject.

Publish-Subscribe Developers Guide Version 7.1

193

10. Synchronizing Data Between Multiple Resources

Step

Description Theobjectisidentifiedinthecrossreferencetablebythefollowingcross referencetablefieldsandthelatchisconsideredopenbecauseisLatchClosedis false: appId CRMsystem objectId Account canonicalKey WM6308 isLatchClosed false

Findingthatthelatchiscurrentlyopen,thenotificationservicebuildsthe canonicaldocumentandpublishesit.Thenotificationserviceinvokesthe pub.synchronization.latch:closeLatch builtinservicetoclosethelatch.Thissetsthe isLatchClosedfieldtotrueandindicatesthatupdatescannotbemadetothis objectandpreventsacircularupdate.Afterthelatchisclosed,the crossreferencetablefieldsareasfollows: appId CRMsystem


3

objectId Account

canonicalKey WM6308

isLatchClosed true

Becausethesourceisalsoatarget,itsubscribestothecanonicaldocumentitjust published.Thetriggerpassesthecanonicaldocumenttoaserviceyoucreateto updatetheresourcewhenadatachangeoccurs.Thisupdateserviceinvokesthe pub.synchronization.latch:isLatchClosed builtinservicetodeterminewhetherthelatch isopenorclosedfortheobject. Findingthatthelatchiscurrentlyclosed,whichindicatesthatthechangehas alreadybeenmade,theupdateservicedoesnotmaketheupdatetotheobject. Theupdateserviceinvokesthepub.synchronization.latch:openLatch builtinserviceto reopenthelatchtoallowfutureupdatestotheobject.Afterthelatchisopen, thecrossreferencetablefieldsareasfollows: appId CRMsystem objectId Account canonicalKey WM6308 isLatchClosed false

Aserviceyoucreatetoupdatethetargetwhenadatachangeoccursreceivesthe canonicaldocument.Thisupdateserviceinvokesthe pub.synchronization.latch:isLatchClosedbuiltinservicetodeterminewhetherthelatch isopenorclosedfortheobject.Initially,thecrossreferencetablefieldsforthe targetobjectareasfollows: appId Billingsystem objectId Account canonicalKey WM6308 isLatchClosed false

Publish-Subscribe Developers Guide Version 7.1

194

10. Synchronizing Data Between Multiple Resources

Step

Description BecauseinitiallytheisLatchClosedcolumnissettofalse,thismeansthelatchis openandupdatescanbemadetothisobject.Tomaketheupdate,theupdate servicemapsinformationfromthecanonicaldocumenttoanativedocumentfor thetargetresourceandsendsthedocumenttothetarget.Thetargetresource usesthisdocumenttomaketheequivalentchange. Theupdateserviceusesthepub.synchronization.latch:closeLatch builtinserviceto closethelatch.Thisindicatesthatupdatescannotbemadetothisobjectand preventsacircularupdate.Afterthelatchisclosed,thecrossreferencetable fieldsareasfollows: appId Billingsystem objectId Account canonicalKey WM6308 isLatchClosed true

5 6

Becausethetargetmadeadatachange,itsendsnotificationofachange. Becausethetargetisalsoasource,whenitreceivesnotificationofadatachange, itattemptstonotifyothertargetsofthedatachange.Anotificationservicethat youcreatetonotifytargetsofadatachangeinvokesthe pub.synchronization.latch:isLatchClosedbuiltinservicetodeterminewhetherthelatch fortheobjectisopenorclosed. Findingthatthelatchisclosed,whichindicatesthatthechangehasalreadybeen made,thenotificationservicedoesnotbuildthecanonicaldocument.The notificationservicesimplyinvokesthepub.synchronization.latch:openLatchbuiltin servicetoreopenthelatch.Becausethelatchisnowopen,futureupdatescanbe madetotheobject.Afterthelatchisopen,thecrossreferencetablefieldsareas follows: appId Billingsystem objectId Account canonicalKey WM6308 isLatchClosed false

Publish-Subscribe Developers Guide Version 7.1

195

10. Synchronizing Data Between Multiple Resources

Tasks to Perform to Set Up Data Synchronization


Thefollowingtableliststhetasksyouneedtoperformtosynchronizedatachangestoan objectthatismaintainedinseveralofyourresources(e.g.,accountinformationacrossall resources).Additionally,thetableliststhesectioninthischapterwhereyoucanfindmore informationabouteachtask. Task Ensurethecrossreferencetableissetup. Definepublishabledocumenttypeforthe notificationdocumentsthateachsourcesendswhen theobjectbeingsynchronizedischanged. Defineanpublishabledocumenttypeforthe canonicaldocument,whichdescribesthedata changeforalltargetresources. DefinelogiconthesourceIntegrationServerto receivethesourceresourcesnotificationdocument, buildthecanonicaldocument,andpublishthe canonicaldocument.Thisincludesthefollowing tasks: Createatriggertosubscribetothesources notificationdocument.Notethatyouonlyneed tocreatethistriggerifthesourcepublishesits notificationdocument. Createaservicethatbuildsthecanonical documentfromthefieldsinthesources notificationdocumentandpublishesthe canonicaldocumenttonotifytargetsofthedata change. For more information, see... PreparingtheCrossReference Tableonpage 197 DefiningHowaSource ResourceSendsNotificationof aDataChangeonpage 198 DefiningtheStructureofthe CanonicalDocumenton page 199 SettingUpKeyCross ReferencingintheSource IntegrationServeron page 200

Publish-Subscribe Developers Guide Version 7.1

196

10. Synchronizing Data Between Multiple Resources

Task DefinelogiconthetargetIntegrationServerthat receivesthecanonicaldocumentandinteractswitha targetresourcetomaketheequivalentchangetothe objectonthetarget.Thisincludesthefollowing tasks: Createatriggerthatsubscribestothecanonical documentthatthesourceIntegrationServer publishes. CreateanISdocumenttypeforthenative documentthatthetargetIntegrationServer sendsthetargetresource,sothetargetcanmake theequivalentchange. Createaservicethatbuildsthetargetnative documentfromfieldsinthecanonical document. Ifyouaredoingnwaysynchronizations,addlogic toperformechosuppressiontotheservicesyou createdforkeycrossreferencing.

For more information, see... SettingUpKeyCross ReferencingintheTarget IntegrationServeron page 205

ForNWaySynchronizations AddEchoSuppressionto Servicesonpage 208

Preparing the Cross-Reference Table


Beforeyoucanusethecrossreferencetable,youmustprepareittoholddata synchronizationdata.Forexample,youmustrunscriptstobuildthecolumnsthatthe crossreferencetablerequires,andconfigureadatabasealias. Forinformationaboutthestepsyouneedtotaketopreparethedatabase,see ConfiguringIntegrationServerforKeyCrossReferenceandEchoSuppressionon page 53. Note: Forinformationaboutthecrossreferencetable,seeKeyCrossReferencingandthe CrossReferenceTableonpage 188andHowtheisLatchedClosedFieldIsUsedforEcho Suppressiononpage 192.

Publish-Subscribe Developers Guide Version 7.1

197

10. Synchronizing Data Between Multiple Resources

Defining How a Source Resource Sends Notification of a Data Change


Beforeyoucreatelogicthatreceivesanotificationdocumentfromasourceresourceand buildsthecanonicaldocument,youneedtodeterminehowthesourceresourceisto notifythesourceIntegrationServerwhenadatachangeoccurs. Thesourceresourcenotifiesotherresourcesofadatachangebysendingadocumentthat describesthechange.Thetypeofdocumentthesourcesendsdependsonwhetheryou are: UsingawebMethodsadapterwiththesource,or Developingyourowninteractionwiththesource. Thefollowingdiagramhighlightsthepartofdatasynchronizationthatthissection addresses.
Canonical Document Notification Source Integration Server Broker Target Integration Server Update

Source Resource

Target Resource

When Using an Adapter with the Source


Whenyouuseanadaptertomanagethesourceresource,configuretheadaptertosendan adapternotificationwhenachangeoccursontheresource.Forinformationabouthowto configuretheadapter,seethedocumentationfortheadapter. Iftheadapterdoesnotcreateanpublishabledocumenttypefortheadapternotification, usethewebMethodsDevelopertodefineanpublishabledocumenttypethatdefinesthe structureoftheadapternotification. Basedontheadapter,theadapterdoesoneofthefollowingtosendtheadapter notification: Publishes the adapter notification. AtriggeronthesourceIntegrationServersubscribesto thispublishabledocumenttype.Whenthetriggerreceivesadocumentthatmatches thepublishabledocumenttypefortheadapternotification,itinvokesthetrigger servicethatbuildsthecanonicaldocument. Directly invokes the service that builds the canonical document. Whentheserviceisdirectly invoked,theadapternotificationissenttotheserviceasinput. Formoreinformationaboutcreatingtheservicethatbuildsthecanonicaldocument,see SettingUpKeyCrossReferencingintheSourceIntegrationServeronpage 200.

Publish-Subscribe Developers Guide Version 7.1

198

10. Synchronizing Data Between Multiple Resources

When Developing Your Own Interaction with the Source


Whenyoudevelopyourownlogictointeractwiththesourceresource,thelogicshould includesendingadocumentwhenadatachangeoccurswithintheresource.Youdefine thedocumentfieldsthatyourequireforthenotification.Besuretoincludeafieldforthe nativeIDtoidentifythechangedobjectonthesource. Afterdeterminingthefieldsthatyouneedinthesourcenativedocument(i.e.,the notification),usethewebMethodsDevelopertodefineanISdocumenttypeforthenative document.Thelogicyoucreatetointeractwiththesourceresourcecandooneofthe followingtosendthesourcenativedocument: Publish the source native document. Ifyourlogicpublishesthesourcesnativedocument, defineapublishabledocumenttypeforthesourcesnativedocument.Atriggeronthe sourceIntegrationServersubscribestothispublishabledocumenttype.Whenthe triggerreceivesadocumentthatmatchesthepublishabledocumenttypeforthe sourcesnativedocument,itinvokesthetriggerservicethatbuildsthecanonical document. Directly invoke the service that builds the canonical document, Whentheserviceisdirectly invoked,thesourcesnativedocumentissenttotheserviceasinput.Ifyourlogic passesthenativedocumenttotheserviceasinput,theISdocumenttypedoesnot needtobepublishable. Formoreinformationaboutcreatingtheservicethatyourlogicshouldinvoke,see SettingUpKeyCrossReferencingintheSourceIntegrationServeronpage 200.

Defining the Structure of the Canonical Document


Thefollowingdiagramhighlightsthepartofdatasynchronizationthatusesthecanonical document.

Notification Source Integration Server

Canonical Document Broker Target Integration Server

Update

Source Resource

Target Resource

Todefinethestructureforcanonicaldocuments,youincludeasupersetofallthefields thatarerequiredtokeepdatasynchronizedbetweentheresources.Additionally,you mustincludeafieldforthecanonicalID.

Publish-Subscribe Developers Guide Version 7.1

199

10. Synchronizing Data Between Multiple Resources

Thefollowingtablelistsoptionsfordefiningthestructureofacanonicaldocument: Use a... Standard format (e.g., cXML,CBL, RosettaNet) Complete custom format Benefit Astandardscommitteehasalreadydecidedthestructure, andyoucanleveragetheirthoughtandeffort. Youdefineauniquestructurethatyoutailorforyour organization.Thedocumentstructuremightbesmaller,and thereforeeasiertomaintainbecauseitonlycontainsthe fieldsyourenterpriserequires.Also,thesmallersizehasa positiveeffectonperformance. Youdefineauniquestructurebystartingwithastructure thatastandardscommitteehasdefined.Youcantake advantageofthethoughtandeffortalreadyputinto decidingthestandardsbasedformat.However,youcan deletefieldsthatyourenterprisemightnotneedandadd additionalfieldsthatarespecifictoyourenterprise.

Custom format based on a standard

Afterdeterminingthefieldsthatyouneedinthecanonicaldocument,usethe webMethodsDevelopertodefineanpublishabledocumenttypeforthecanonical document.Formoreinformationabouthowtocreatepublishabledocumenttypes,see Chapter 5,WorkingwithPublishableDocumentTypes.

Setting Up Key Cross-Referencing in the Source Integration Server


ThesourceresourcesendsanotificationdocumenttothesourceIntegrationServerwhen adatachangeoccursinthesourceresource.Thissectiondescribeshowtodefinethelogic forthesourceIntegrationServerto: Receivethenotificationdocument, Usenotificationdocumenttobuildthecanonicaldocument,and Publishthecanonicaldocument. Youcreateaservicetobuildandpublishthecanonicaldocument.Thelogictobuildthe canonicaldocumentusesbuiltinservicesforkeycrossreferencing,whicharedescribed inBuiltInServicesforKeyCrossReferencingonpage 201.Inthischapter,theservice thatbuildsthecanonicaldocumentisreferredtoasanotificationservice. Youshouldimplementkeycrossreferencingforbothonewayandnway synchronizations.

Publish-Subscribe Developers Guide Version 7.1

200

10. Synchronizing Data Between Multiple Resources

Note: Foranoverviewofkeycrossreferencing,includingtheproblemkey crossreferencingsolvesandhowkeycrossreferencingworks,seeKeyCross ReferencingandtheCrossReferenceTableonpage 188. Thefollowingdiagramhighlightsthepartofdatasynchronizationthatthissection addresses.


Canonical Document Notification Source Integration Server Broker Target Integration Server Update

Source Resource

Target Resource

Built-In Services for Key Cross-Referencing


ThefollowingtableliststhebuiltservicesthatwebMethodsprovidesforkey crossreferencing.Thekeycrossreferencingservicesarelocatedinthe pub.synchronization.xreffolder.Formoreinformationabouttheseservices,seethewebMethods IntegrationServerBuiltInServicesReference. Service createXReference Description UsedbythesourcetoassignacanonicalIDandaddarowtothe crossreferencetabletocreateacrossreferencebetweenthecanonical IDandthesourcesnativeID.ToassignthevalueforthecanonicalID, youcaneitherspecifythevalueasinputtothecreateXReferenceservice orhavethecreateXReferenceservicegeneratethevalue. Usedbyatargettoaddarowtothecrossreferencetabletoaddthe targetscrossreferencebetweenanexistingcanonicalID(whichthe sourceadded)andthetargetsnativeID. RetrievesthevalueofthecanonicalIDfromthecrossreferencetable thatcorrespondstothenativeIDthatyouspecifyasinputtothe getCanonicalKeyservice. RetrievesthevalueofthenativeIDfromthecrossreferencetablethat correspondstothecanonicalIDthatyouspecifyasinputtothe getNativeIdservice.

insertXReference

getCanonicalKey

getNativeId

Publish-Subscribe Developers Guide Version 7.1

201

10. Synchronizing Data Between Multiple Resources

Setting up the Source Integration Server


TosetupkeycrossreferencinginthesourceIntegrationServer: Create a trigger to subscribe to the source resources notification document, if applicable.You onlyneedtodefineatriggerthatsubscribestothenotificationdocumentifthesource resourcepublishesthenotificationdocument(i.e.,eitheranadapternotificationor othernativedocument).Ifthesourcedirectlypassesthenotificationdocumenttoa serviceasinput,youdonotneedtodefineatrigger.Ifyouneedtodefineatrigger, definethetriggerthat: Subscribestothepublishabledocumenttypethatdefinesthenotification document(i.e.,eitheranadapternotificationorothernativedocument). Definesthetriggerservicetobetheservicethatbuildsthecanonicaldocument fromthenotificationdocument. Formoreinformation,seeChapter 7,WorkingwithTriggers. Create the trigger service that builds the canonical documentandpublishesthecanonical documenttopropagatethedatachangetoalltargetresources.Youneedtocreatea servicethatputsthedatachangeinformationintoaneutralformatthatalltargets understand.Theneutralformatisthecanonicaldocument. Theservicebuildsthecanonicaldocumentbymappinginformationfromthe notificationdocumenttothecanonicaldocument.ToobtainthecanonicalIDforthe canonicaldocument,theserviceusesthebuiltinkeycrossreferencingservices pub.synchronization.xref:getCanonicalKey and/orpub.synchronization.xref:createXReference,as showninthesamplelogicbelow.Afterformingthecanonicaldocument,yourservice publishesthecanonicaldocument.
1

2 3 4 5
6

Publish-Subscribe Developers Guide Version 7.1

202

10. Synchronizing Data Between Multiple Resources

Step
1

Description Determine whether there is already a canonical ID. Invokethepub.synchronization.xref:getCanonicalKeyservicetolocatearowinthe crossreferencetableforthesourceobject.Iftherowalreadyexists,a canonicalIDalreadyexistsforthesourceobject.PassthegetCanonicalKey servicethefollowinginputsthatidentifythesourceobject: In this input variable... appId objectId nativeId Specify... Theidentificationoftheapplication(e.g.,CRMsystem). Thestringthatyouassignedtoidentifytheobject(e.g., Account).ThisstringisreferredtoastheobjectID. ThenativeIDfromthenotificationdocument(e.g.,adapter notification),whichwasreceivedasinputtoyourservice.

IfthegetCanonicalKeyservicefindsarowinthecrossreferencetablethat matchestheinputinformation,itreturnsthevalueofthecanonicalIDinthe canonicalKeyoutputvariable.Ifnorowisfound,thevalueofthecanonicalKey outputvariableisblank(i.e.,anemptystring).Formoreinformationabout thegetCanonicalKeyservice,seethewebMethodsIntegrationServerBuiltIn ServicesReference.


2

Split logic based on whether the canonical ID already exists. UseaBRANCHflowsteptosplitthelogic.SettheSwitchpropertyofthe BRANCHflowsteptocanonicalKey. Build a sequence of steps to execute when the canonical ID does not already exist. UndertheBRANCHflowstepisasinglesequenceofstepsthatshouldbe executedonlyifacanonicalIDwasnotfound.NotethattheLabelproperty fortheSEQUENCEflowstepissettoblank.Atruntime,theservermatches thevalueofthecanonicalKeyvariabletotheLabelfieldtodeterminewhether toexecutethesequence.BecausethecanonicalKeyvariableissettoblank(i.e., anemptystring),thelabelfieldmustalsobeblank. Important! Donotuse$nullfortheLabelproperty.Anemptystringisnot consideredanull.

Publish-Subscribe Developers Guide Version 7.1

203

10. Synchronizing Data Between Multiple Resources

Step
4

Description If there is no canonical ID, define one. Ifarowforthesourceobjectisnotfoundinthecrossreferencetable,thereis nocanonicalIDforthesourceobject.DefineacanonicalIDbyaddingarow tothecrossreferencetabletocrossreferencethesourcenativeIDwitha canonicalID.Youaddtherowbyinvokingthe pub.synchronization.xref:createXReferenceservice.PassthecreateXReferenceservice thefollowing: In this input variable... appId objectId nativeId canonicalKey Specify... Theidentificationoftheapplication(e.g.,CRMsystem). Theobjecttype(e.g.,Account). ThenativeIDfromthenotificationdocument(e.g.,adapter notification),whichwasreceivedasinputtoyourservice. (optional)ThevalueyouwanttoassignthecanonicalID.

IfyoudonotspecifyavalueforthecanonicalKeyinputvariable,the createXReferenceservicegeneratesacanonicalIDforyou.Formore informationaboutthecreateXReferenceservice,seethewebMethodsIntegration ServerBuiltInServicesReference.


5

Build the canonical document. Mapfieldsfromthenotificationdocument(e.g.,adapternotification)tothe fieldsofthecanonicaldocument.MakesureyoumapthecanonicalID generatedinthelaststeptothecanonicalIDfieldofthecanonical document. Thenotificationdocumenthasthestructurethatyoupreviouslydefined withathepublishabledocumenttype.SeeDefiningHowaSource ResourceSendsNotificationofaDataChangeonpage 198.Similarly,the canonicaldocumenthasthestructurethatyoupreviouslydefinedwitha publishabledocumenttype.SeeDefiningtheStructureoftheCanonical Documentonpage 199. Note: AlthoughthissamplelogicshowsonlyasingleMAPflowstep,you mightneedtouseadditionalflowstepsorpossiblycreateaseparateservice tobuildthecanonicaldocument.

Publish the canonical document. Aftertheservicehasformedthecanonicaldocument,invokethe pub.publish:publish servicetopublishthecanonicaldocumenttotheBroker.

Publish-Subscribe Developers Guide Version 7.1

204

10. Synchronizing Data Between Multiple Resources

Setting Up Key Cross-Referencing in the Target Integration Server


ThecanonicaldocumentispublishedtothetargetIntegrationServers.Thissection describeshowtodefinethelogicforatargetIntegrationServerto: Receivethecanonicaldocument. Usethecanonicaldocumenttobuildadocumenttoinformthetargetresourceofthe datachange.Thisdocumenthasastructurethatisnativetothetargetresource. Sendthenativedocumenttothetargetresource,sothetargetresourcecanmakethe equivalentdatachange. Youcreateaservicetobuildthenativedocumentandsendittothetargetresource.The logictobuildthenativedocumentusesbuiltinservicesforkeycrossreferencing,which aredescribedinBuiltInServicesforKeyCrossReferencingonpage 201.Inthis chapter,theservicethatreceivesthecanonicaldocumentandbuildsanativedocumentis referredtoasanupdateservice. Thefollowingdiagramhighlightsthepartofdatasynchronizationthatthissection addresses.
Canonical Document Notification Source Integration Server Broker Target Integration Server Update

Source Resource

Target Resource

TosetupkeycrossreferencinginthetargetIntegrationServer: Create a trigger that subscribes to the canonical document that the source Integration Server publishes.OnthetargetIntegrationServers,defineatriggerthat: Subscribestothepublishabledocumenttypethatdefinesthecanonical document. Definesthetriggerservicetobetheservicethatbuildsthebuildsanative documentforthetargetresource. Formoreinformation,seeChapter 7,WorkingwithTriggers. Create an IS document type thatdefinesthestructureofthedocumentthatthetarget IntegrationServerneedstosendtothetargetresourcetonotifyitofadatachange. FormoreinformationabouthowtocreateISdocumenttypes,seethewebMethods DeveloperUsersGuide. Create the trigger service that uses the canonical document to build the target native document and sends the native document to the target resource.Theservicereceivesthecanonical

Publish-Subscribe Developers Guide Version 7.1

205

10. Synchronizing Data Between Multiple Resources

document,whichcontainsthedescriptionofthedatachangetomake.However, typicallythetargetresourcewillnotunderstandthecanonicaldocument.Rather,the targetresourcerequiresadocumentinitsownnativeformat. Theservicecanbuildthenativedocumentforthetargetresourcebymapping informationfromthecanonicaldocumenttothetargetresourcesnativedocument format.MakesureyouincludethenativeIDinthisdocument.Toobtainthenative ID,invokethepub.synchronization.xref:getNativeIdbuiltinservice.IfthenativeIDis crossreferencedwiththecanonicalIDinthecrossreferencetable,thisservicereturns thenativeID.Ifnocrossreferencehasbeensetupfortheobject,youwillneedto determinethebestwaytoobtainthenativeID. Afterformingthenativedocument,thetriggerserviceinteractswiththetarget resourcetomakethedatachange. Note: ForadescriptionofthebuiltinservicesthatwebMethodsprovideforkey crossreferencing,seeBuiltInServicesforKeyCrossReferencingonpage 201. Thefollowingshowssamplelogicfortheupdateservice.Seethetableafterthediagram formoreinformation.
1

2 3 4 5
6

Step
1

Description Obtain the native ID for the target object if there is an entry for the target object in the cross-reference table. Invokethepub.synchronization.xref:getNativeIdservicetolocatearowinthecross referencetableforthetargetobject.Iftherowalreadyexists,therowcontains thenativeIDforthetargetobject.PassthegetNativeIdservicethefollowinginputs thatidentifythetargetobject: In this input variable... appId objectId canonicalKey Specify... Theidentificationoftheapplication(e.g.,Billingsystem). Theobjecttype(e.g.,Account). ThecanonicalIDfromthecanonicaldocument,whichwas receivedasinputtoyourservice.

Publish-Subscribe Developers Guide Version 7.1

206

10. Synchronizing Data Between Multiple Resources

Step

Description IfthegetNativeIdservicefindsarowthatmatchestheinputinformation,itreturns thevalueofthenativeIDinthenativeIdoutputvariable.Ifnorowisfound,the valueofthenativeIdoutputvariableisblank(i.e.,anemptystring).Formore informationaboutthegetNativeIdservice,seethewebMethodsIntegrationServer BuiltInServicesReference.

Split logic based on whether a native ID was obtained for the target resource. UseaBRANCHflowsteptosplitthelogic.SettheSwitchpropertyofthe BRANCHflowsteptonativeId,toindicatethatyouwanttosplitlogicbased onthevalueofthenativeIdpipelinevariable. Build a sequence of steps to execute when the native ID is not obtained. UndertheBRANCHflowstepisasinglesequenceofstepstoperformonlyifa nativeIDwasnotfound.NotethattheLabelpropertyfortheSEQUENCEflow stepissettoblank.Atruntime,theservermatchesthevalueofthenativeID variabletothelabelfieldtodeterminewhethertoexecutethesequence.Because thenativeIdvariableissettoblank(i.e.,anemptystring),theLabelfieldmustalso beblank. Important! Donotuse$nullfortheLabelproperty.Anemptystringisnot considerednull.

If no native ID was obtained, specify one. IfanativeIDwasnotfound,addarowtothecrossreferencetableforthetarget objecttocrossreferencethetargetnativeIDwiththecanonicalIDbyinvoking thepub.synchronization.xref:insertXReferenceservice.PasstheinsertXReferenceservice: In this input variable... appId objectId nativeId canonicalKey Specify... Theidentificationoftheapplication(e.g.,Billingsystem). Theobjecttype(e.g.,Account). ThenativeIDfortheobjectinthetargetresource.Youmust determinewhatthenativeIDshouldbe. ThecanonicalIDfromthecanonicaldocument,whichwas receivedasinputtoyourservice.

FormoreinformationabouttheinsertXReferenceservice,seethewebMethods IntegrationServerBuiltInServicesReference.

Publish-Subscribe Developers Guide Version 7.1

207

10. Synchronizing Data Between Multiple Resources

Step
5

Description Build the native document for the target resource. Tobuildthenativedocument,mapfieldsfromthecanonicaldocumenttothe fieldsofnativedocument.AlsomapthenativeIDtothenativedocument. Thecanonicaldocumenthasthestructurethatyoupreviouslydefinedwitha publishabledocumenttype.SeeDefiningtheStructureoftheCanonical Documentonpage 199.Similarly,thenativedocumenthasthestructurethat youpreviouslydefinedwithanISdocumenttype. Note: AlthoughthissamplelogicshowsonlyasingleMAPflowstep,youmight needtouseadditionalflowstepsorpossiblycreateaseparateservicetobuild thenativedocumentforthetargetresource.

Invoke a service to send the native document to the target resource, so the target resource can make the equivalent change. Createaservicethatsendsthenativedocumenttothetarget. Ifyouuseanadapterwithyourtargetresource,youcanuseanadapterservice toupdatethetargetresource.Formoreinformationaboutadapterservices,see thedocumentationforyouradapter.

For N-Way Synchronizations Add Echo Suppression to Services


Whenyouusenwaysynchronization,youneedtoincludelogicthatperformsecho suppressiontothe: NotificationservicesthatrunonsourceIntegrationServers.Foradescriptionof notificationservices,seeSettingUpKeyCrossReferencingintheSourceIntegration Serveronpage 200. UpdateservicesthatrunontargetIntegrationServers.Foradescriptionofupdate services,seeSettingUpKeyCrossReferencingintheTargetIntegrationServeron page 205. Echosuppressionlogicblockscircularupdatingofdatachangesfromoccurring.Echo suppressionisnotneededwhenyouuseonewaysynchronization. Note: Foranoverviewofechosuppression,includinginformationabouthowecho suppressionsolvestheproblemofcircularupdating,seeEchoSuppressionforNWay Synchronizationsonpage 191.

Publish-Subscribe Developers Guide Version 7.1

208

10. Synchronizing Data Between Multiple Resources

Built-in Services for Echo Suppression


ThefollowingtableliststhebuiltservicesthatwebMethodsprovidesforecho suppression.Theechosuppressionservicesarelocatedinthepub.synchronization.latchfolder. Service closeLatch Description ClosesthelatchforthespecifiedcanonicalID,applicationID(appId), andobjecttype(objectId).Toclosethelatch,theisLatchClosedfieldof thecrossreferencetableissettotrue.Aclosedlatchindicatesthatthe resourcedescribedinthecrossreferencerowcannotbeacteduponuntil thelatchisopenusingtheopenLatchservice. Determineswhetherthelatchisopenorclosedforthespecified canonicalID,applicationID(appId),andobjecttype(objectId).Tocheck thestatusofthelatch,theserviceusestheisLatchedClosedfieldofthe crossreferencetable.Theoutputprovidesastatusoftrue(thelatchis closed)orfalse(thelatchisopen). OpensthelatchforthespecifiedcanonicalID,applicationID(appId), andobjecttype(objectId).Toopenthelatch,theisLatchClosedfieldof thecrossreferencetableissettofalse.Anopenlatchindicatesthatthe resourcedescribedinthecrossreferencerowcanbeactedupon.

isLatchClosed

openLatch

Adding Echo Suppression to Notification Services


Theechosuppressionlogicinanotificationservicedetermineswhetheralatchisopenor closedbeforeitattemptstobuildandpublishthecanonicaldocument. If the latch is open,theresourceisthesourceofthedatachange.Inthiscase,the notificationserviceonthesourceIntegrationServerbuildsthecanonicaldocument andpublishesit.Thenotificationserviceshouldincludelogicthatclosesthelatchto preventacircularupdate. If the latch is closed,theresourcehasalreadymadethedatachange.Inthiscase,the notificationservicedoesnotneedtobuildthecanonicaldocumenttonotifyresources aboutthedatachangebecausethenotificationserviceonthesourceIntegration Serverhasalreadydoneso.Thenotificationserviceshouldsimplyreopenthelatch andterminateprocessing.

Publish-Subscribe Developers Guide Version 7.1

209

10. Synchronizing Data Between Multiple Resources

Thefollowingdiagramhighlightsthepartofdatasynchronizationthatthissection addresses.
Notification Service latch is open Send notification. Notification Update

Source Resource

Source Integration Server

Broker

Target Integration Server

Notification

Target Resource

Notification Service latch is closed Do not publish notification.

Incorporating Echo Suppression Logic into a Notification Service


Thefollowingshowsthesamplenotificationservicewithechosuppressionlogicaddedto it.ThesamplenotificationservicewaspresentedinSettingUpKeyCrossReferencingin theSourceIntegrationServeronpage 200alongwithadescriptionofitsflowsteps, whichareunnumberedinthesamplebelow.Thenumberedflowstepsinthesample belowaretheflowstepsaddedforechosuppression.Formoreinformationaboutthe numberedflowsteps,seethetableafterthediagram.

2 3 4

5
6

Publish-Subscribe Developers Guide Version 7.1

210

10. Synchronizing Data Between Multiple Resources

Step
1

Description Determine whether the latch is open or closed for the object being changed. Invokethepub.synchronization.latch:isLatchClosedservicetolocatearowinthe crossreferencetablefortheobjectthathaschangedandforwhichyouwantto sendnotification.PasstheisLatchClosedservicethefollowinginputsthatidentify theobject: In this input variable... appId objectId canonicalKey Specify... Theidentificationoftheapplication(e.g.,CRMsystem). Theobjecttype(e.g.,Account). ThecanonicalID.

TheisLatchClosedserviceusestheisLatchClosedfieldfromthematchingrowto determinewhetherthelatchisopenorclosed.IftheisLatchfieldisfalse,the latchisopen,andtheisLatchClosed servicereturnsfalseintheisLatchClosed outputvariable.IftheisLatchfieldistrue,thelatchisclosed,andtheservice returnstrue.FormoreinformationabouttheisLatchClosedservice,seethe webMethodsIntegrationServerBuiltInServicesReference.


2

Split logic based on whether the latch is open or closed. UseaBRANCHflowsteptosplitthelogic.SettheSwitchpropertyofthe BRANCHtoisLatchClosed,toindicatethatyouwanttosplitlogicbasedon thevalueoftheisLatchClosedpipelinevariable. Build a sequence of steps to execute when the latch is open. BecausetheLabelpropertyfortheSEQUENCEflowstepissettofalse,this sequenceofoperationsisexecutedwhentheisLatchClosedvariableisfalse, meaningthelatchisopen.Whenthelatchisopen,thetargetresourceshavenot yetbeennotifiedofthedatachange.Thissequenceofstepsbuildsandpublishes thecanonicaldocument. Close the latch for the object. Whenthelatchisopen,thefirststepistoclosethelatch.Byclosingthelatch beforepublishingthecanonicaldocument,youremoveanychancethatthe IntegrationServerwillreceiveandactonthepublishedcanonicaldocument. Toclosethelatch,invokethepub.synchronization.latch:closeLatchservice.Passthe closeLatchservicethesameinputvariablesthatwerepassedtothe pub.sychronization.latch:isLatchClosedserviceinstep1above.Formoreinformation aboutthecloseLatchservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Publish-Subscribe Developers Guide Version 7.1

211

10. Synchronizing Data Between Multiple Resources

Step
5

Description Build a sequence of steps to execute when the latch is closed. BecausetheLabelpropertyfortheSEQUENCEflowoperationissettotrue,this sequenceofstepsisexecutedwhentheisLatchClosedvariableistrue,meaning thelatchisclosed.Whenthelatchisclosed,notificationofthedatachangehas alreadybeenpublished.Asaresult,thenotificationservicedoesnotneedto buildorpublishthecanonicaldocument.Thissequenceofstepssimplyreopens thelatch. Re-open the latch. Reopenthelatchtoresetthelatchforfuturedatachanges.Toreopenthelatch, invokethepub.synchronization.latch:openLatchservice.PasstheopenLatchservicethe sameinputvariablesthatwerepassedtothepub.sychronization.latch:isLatchClosed serviceinstep1above.FormoreinformationabouttheopenLatchservice,seethe webMethodsIntegrationServerBuiltInServicesReference.

Important! Ifmultipleresourceswillmakechangestothesameobjectsimultaneouslyor nearsimultaneously,echosuppressioncannotguaranteesuccessfulupdating.Ifyou expectsimultaneousornearsimultaneousupdates,youmusttakeadditionalsteps: 1 2 Whendefiningthestructureofacanonicaldocument,includeatrackingfieldthat identifiesthesourceofthechangetothecanonicaldocumentstructure. InthenotificationserviceincludeafilterorBRANCHtotestonthesourcefieldto determinewhethertosendthenotification.

Adding Echo Suppression to Update Trigger Services


Theupdatetriggerservicereceivesthecanonicaldocumentthatdescribesadatachange. Theechosuppressionlogicinanupdateservicedetermineswhetheralatchisopenor closedbeforeitattemptstousetheinformationinthecanonicaldocumenttoupdatea resourcewiththedatachange. If the latch is open,thedatachangehasnotyetbeenmadetotheresource.Inthiscase, theupdateservicebuildsandsendsthenativedocumentthatinformsthetarget resourceofthedatachange.Theupdateserviceclosesthelatchtopreventacircular update. If the latch is closed,theresourcewasthesourceofthedatachangeandhasalready madethedatachange.Inthiscase,theupdateservicedoesnotneedbuildandsend thenativedocument.Theupdateserviceshouldsimplyreopenthelatchand terminateprocessing.

Publish-Subscribe Developers Guide Version 7.1

212

10. Synchronizing Data Between Multiple Resources

Thefollowingdiagramhighlightsthepartofdatasynchronizationthatthissection addresses.

Update Service latch is open Update resource. Update

Notification

Source Integration Server Update Service latch is closed Do not update resource.

Broker

Target Integration Server

Source Resource

Notification

Target Resource

Incorporating Echo Suppression Logic into an Update Service


Thefollowingshowsthesampleupdateservicewithechosuppressionlogicaddedtoit. ThesampleupdateservicewaspresentedinSettingUpKeyCrossReferencinginthe TargetIntegrationServeronpage 205alongwithadescriptionofitsflowsteps,which areunnumberedinthesamplebelow.Thenumberedflowstepsinthesamplebeloware theflowstepsaddedforechosuppression.Formoreinformationaboutthenumbered flowsteps,seethetableafterthediagram.
1

2 3

5
6

Publish-Subscribe Developers Guide Version 7.1

213

10. Synchronizing Data Between Multiple Resources

Step
1

Description Determine whether the latch is open or closed for the changed object. Invokethepub.synchronization.latch:isLatchClosedservicetolocatearowinthe crossreferencetableforthechangedobject.PasstheisLatchClosedservicethe followinginputsthatidentifytheobject: In this input variable... appId objectId canonicalKey Specify... Theidentificationoftheapplication(e.g.,Billingsystem). Theobjecttype(e.g.,Account). ThecanonicalID.

TheisLatchClosedserviceusestheisLatchClosedfieldfromthematchingrowto determinewhetherthelatchisopenorclosed.IftheisLatchClosedfieldis false,thelatchisopen,andtheisLatchClosed servicereturnsfalseinthe isLatchClosedoutputvariable.IftheisLatchClosedfieldistrue,thelatchis closed,andtheservicereturnstrue.Formoreinformationaboutthe isLatchClosedservice,seethewebMethodsIntegrationServerBuiltInServices Reference.


2

Split logic based on whether the latch is open or closed. UseaBRANCHflowsteptosplitthelogic.SettheSwitchpropertyofthe BRANCHtoisLatchClosed,toindicatethatyouwanttosplitlogicbasedon thevalueoftheisLatchClosedpipelinevariable. Build a sequence of steps to execute when the latch is open. BecausetheLabelpropertyfortheSEQUENCEflowstepissettofalse,this sequenceofoperationsisexecutedwhentheisLatchClosedvariableisfalse, meaningthelatchisopen.Whenthelatchisopen,thetargetresourcehasnotyet madetheequivalentdatachange.Thissequenceofstepsbuildsandsendsa nativedocumentthatthetargetresourceusestomaketheequivalentchange. Close the latch. Whenthelatchisopen,closethelatchbeforesendingthenativedocumentto thetargetresource.Fornwaysynchronizationsbecauseatargetisalsoasource, whentheresourcereceivesandmakestheequivalentdatachange,theresource thensendsnotificationofadatachange.Byclosingthelatchbeforesendingthe nativedocumenttothetargetresource,youremoveanychancethatthe IntegrationServerwillreceiveandactonanotificationdocumentbeingsentby theresource. Toclosethelatch,invokethepub.synchronization.latch:closeLatchservice.Passthe closeLatchservicethesameinputvariablesthatwerepassedtothe pub.sychronization.latch:isLatchClosedserviceinstep1above.Formoreinformation aboutthecloseLatchservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Publish-Subscribe Developers Guide Version 7.1

214

10. Synchronizing Data Between Multiple Resources

Step
5

Description Build a sequence of steps to execute when the latch is closed. BecausetheLabelpropertyfortheSEQUENCEflowstepissettotrue,this sequenceofstepsisexecutedwhentheisLatchClosedvariableistrue,meaning thelatchisclosed.Whenthelatchisclosed,theresourcehasalreadymadethe equivalentdatachange.Asaresult,theupdateservicedoesnotneedtobuildor sendanativedocumenttothetargetresource. Re-open the latch. Reopenthelatchtoresetthelatchforfuturedatachanges.Toreopenthelatch, invokethepub.synchronization.latch:openLatchservice.PasstheopenLatchservicethe sameinputvariablesthatwerepassedtothepub.sychronization.latch:isLatchClosed serviceinstep1above.FormoreinformationabouttheopenLatchservice,seethe webMethodsIntegrationServerBuiltInServicesReference.

Important! Ifmultipleresourceswillmakechangestothesameobjectsimultaneouslyor nearsimultaneously,echosuppressioncannotguaranteesuccessfulupdating.Ifyou expectsimultaneousornearsimultaneousupdates,youmusttakeadditionalsteps: 1 2 Whendefiningthestructureofacanonicaldocument,includeatrackingfieldthat identifiesthesourceofthechangetothecanonicaldocumentstructure. IntheupdateserviceincludeafilterorBRANCHtotestonthesourcefieldto determinewhethertoupdatetheobject.

Publish-Subscribe Developers Guide Version 7.1

215

10. Synchronizing Data Between Multiple Resources

Publish-Subscribe Developers Guide Version 7.1

216

Appendix A. Naming Guidelines

Naming Rules for webMethods Developer Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Naming Rules for webMethods Broker Document Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Publish-Subscribe Developers Guide Version 7.1

217

A. Naming Guidelines

Naming Rules for webMethods Developer Elements


webMethodsDeveloperplacessomerestrictionsonthecharactersthatcanbeusedin element,package,andfoldernames.Specifically,elementandpackagenamescannot contain: ReservedwordsandcharactersthatareusedinJavaorC/C++(suchasfor,while,and if ) Digitsastheirfirstcharacter Spaces Controlcharactersandspecialcharacterslikeperiods(.),including: ? & % ' @ * ^ : # ! $ = | ] ) } [ ( { " . ` + / > , \ < ~ ;

CharactersoutsideofthebasicASCIIcharacterset,suchasmultibytecharacters Ifyouspecifyanamethatdisregardstheserestrictions,Developerdisplaysanerror message.Whenthishappens,useadifferentnameortryaddingaletterornumbertothe nametomakeitvalid.

Naming Rules for webMethods Broker Document Fields


Whenyousaveatrigger,theIntegrationServerevaluatesthefiltertomakesureitusesthe propersyntax.SomefieldnamesthatarevalidontheIntegrationServerarenotvalidon theBroker.IfyouwantafiltertobesavedontheBroker,youneedtomakesurethatfields infiltersconformtothefollowingrules: Namesmustbeunicodevalues. Charactersmustbealphanumeric,underscore,andpluscodesover\u009F. Thefirstcharactercannotbeanumericcharacter(09)oranunderscore(_). Namescannotcontainsymbols,spaces,ornonprintableANSI. Followingisalistofreservedwords: acl byte const event any char date eventtype boolean client double extends broker clientgroup enum false

Publish-Subscribe Developers Guide Version 7.1

218

A. Naming Guidelines

family import nal string typedef unicode_char

final infoset null struct unicode_char unicode_string

float int server territory unicode_string union

host long short true typedef unsigned

IftheIntegrationServerdeterminesthatthesyntaxisvalidfortheBroker,itsavesthe filterwiththesubscriptionontheBroker.IftheIntegrationServerdeterminesthatthe filtersyntaxisnotvalidontheBrokerorifattemptingtosavethefilterontheBroker wouldcauseanerror,theIntegrationServersavesthesubscriptionontheBrokerwithout thefilter.ThefilterwillbesavedonlyontheIntegrationServer.

Publish-Subscribe Developers Guide Version 7.1

219

A. Naming Guidelines

Publish-Subscribe Developers Guide Version 7.1

220

Appendix B. Building a Resource Monitoring Service

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Publish-Subscribe Developers Guide Version 7.1

221

B. Building a Resource Monitoring Service

Overview
Aresourcemonitoringserviceisaservicethatyoucreatetochecktheavailabilityof resourcesusedbyatrigger.IntegrationServerschedulesasystemtasktoexecutea resourcemonitoringserviceafteritsuspendsatrigger.Specifically,IntegrationServer suspendsatriggerandinvokestheassociatedresourcemonitoringservicewhenoneof thefollowingoccurs: Duringexactlyonceprocessing,thedocumentresolverserviceendsbecauseofan ISRuntimeExceptionandthe watt.server.trigger.preprocess.suspendAndRetryOnErrorpropertyissetto true(thedefault). Aretryfailureoccursandtheconfiguredretrybehaviorissuspendandretrylater Whentheresourcemonitoringserviceindicatesthattheresourcesusedbythetriggerare available,IntegrationServerresumesthetrigger.

Service Requirements
Aresourcemonitoringservicemustdothefollowing: Usethepub.trigger:resourceMonitoringSpecastheservicesignature. Checktheavailabilityoftheresourcesusedbythedocumentresolverserviceandall thetriggerservicesassociatedwithatrigger.Keepinmindthateachconditionina triggercanbeassociatedwithadifferenttriggerservice.However,youcanonly specifyoneresourcemonitoringservicepertrigger. ReturnavalueoftrueorfalsefortheisAvailableoutputparameter.Theauthorof theresourcemonitoringservicedetermineswhatcriteriamakesaresourceavailable. Catchandhandleanyexceptionsthatmightoccur.Iftheresourcemonitoringservice endsbecauseofanexception,IntegrationServerlogstheexceptionandcontinuesasif theresourcemonitoringservicereturnedavalueoffalsefortheisAvailableoutput parameter. Thesameresourcemonitoringservicecanbeusedformultipletriggers.Whentheservice indicatesthatresourcesareavailable,IntegrationServerresumesallthetriggersthatuse theresourcemonitoringservice.

Publish-Subscribe Developers Guide Version 7.1

222

Index

Index
A
acknowledgement queue description 132 effect on network traffic 133 effect on server threads 133 performance impact 133 setting size 133 Acknowledgement Queue Size property 132 acknowledgement, description 66 activation field 93 activation ID All (AND) joins 174 description 94 Only one (XOR) joins 177 adapter notification data synchronization 184, 185, 198 description 15, 65 moving in Navigation panel 66 All (AND) join description 120, 172 satisfying 174 subscribe path 174 time-out 128 AND join. See All (AND) join. Any (OR) join description 120, 172 subscribe path 173 appId field 189 asynchronous request/reply async flag 100, 106 description 23, 97, 104 retrieving reply 100 tag field 100, 106 waiting for reply 100 at-least-once processing description 154 guaranteed storage 67 at-most-once processing description 154 volatile storage 66

B
Broker changing, effect on document type synchronization status 76 configuring 48 deadletter queue 20 description 13 filters evaluating and saving 122 saving partially 122 valid field names 218 keep-alive messages keep-alive period 50 response time 51 retry limit 51 native event handling 53 publishing to when disconnected 21 switching to Broker in a new territory 48 version effect on duplicate detection 166 effect on exactly-once processing statistics 169 Broker Coder cannot decode message 77 Broker doc type property description 62 folderName::documentTypeName 63 Not Publishable 64 Publishable Locally Only 64 wm::is::folderName::documentTypeName 63 Broker document types creating from publishable document type 62 editing with Enterprise Integrator 71 field name restrictions 59, 218 handling native events 53 name created by Integration Server 57 using to create publishable document type 59 Broker events, native 69

Publish-Subscribe Developers Guide Version 7.1

223

Index

Broker/local trigger, definition of 9 built-in services closeLatch 194, 195, 209, 211, 214 createTrigger 121 createXReference 201, 202, 204 deleteTrigger 150 deliver 92 deliverAndWait 92 echo suppression 209 getCanonicalKey 201, 202, 203 getNativeId 201, 206 getRedeliveryCount 159 getRetryCount 147 insertXReference 201, 207 isLatchClosed 193, 194, 195, 209, 211, 214 key cross-referencing 201 openLatch 194, 195, 209, 212, 215 publish 92 publishAndWait 92 reply 92 throwExceptionForRetry 141 waitForReply 92

C
canonical documents advantages of 187 building native document from 208 creating 204 creating service that builds 202 creating trigger that subscribes to 205 defining structure of 200 description 16, 184, 185, 187 echo suppression 209 obtaining canonical ID for 190, 203, 204 publishable document type 200 publishing 204 standard vs. custom formats 200 structure 188 trigger subscriptions 186 canonical ID adding mapping to native ID 204, 207 adding to cross-reference table 204 creating 204

cross-reference table 189 description 188 mapping to native IDs 188 obtaining for canonical document 190, 203, 204 obtaining from cross-reference table 203 service to use to obtain ID 201 canonicalKey field 189 capacity, for trigger queues 130 client queue storage, overriding document storage 67 client-side queuing, enabling or disabling 52 closeLatch service description 209 example 211, 214 when to use 194 closing latch 194 clusters creating triggers in 118 deleting triggers in 150 disabling or enabling a trigger in 127 document delivery and failover 103 processing join conditions 181 serial document processing behavior 134 synchronizing publishable document types in 85 time drift and duplicate detection 164 com.wm.app.b2b.server.ISRuntimeException class 141 completed status, for document history entries 160 concurrent processing, description 136 conditions (triggers) adding 125 All (AND) time-out 128 changing order 126 join condition, testing 152 multiple 123 Only one (XOR) time-out 129 simple conditions 118 configuring Broker connection 48 cross-reference table 197 exactly-once processing 166 key cross-reference and echo supression storage 53 native Broker event handling 53 server parameters 50 user account for trigger services 49

Publish-Subscribe Developers Guide Version 7.1

224

Index

conventions used in this document 9 Created Locally synchronization status 76 createTrigger service 121 createXReference service description 201 example 204 cross-reference table adding new row 204, 207 configuring 197 fields appId 189 canonical ID 189 canonicalKey 189 example 189 identification of objects 189 identification of resources 189 isLatchClosed, purpose 192 isLatchClosed, when false 192 isLatchClosed, when true 192 nativeId 189 objectId 189 how used for key cross-referencing 189 obtaining canonical ID from 203 isLatchClosed value from 211, 214 native ID from 207 purpose of 188

D
data synchronization closing latch 194, 211, 214 creating canonical ID 204 trigger service that builds canonical document 202 trigger service that builds target native document 205 trigger to subscribe to canonical document 205 trigger to subscribe to notification document 202 cross-reference table used for key cross-referencing 189 description 12, 184 determining whether latch is open or closed 193, 211, 214 determining whether to update an object 193 echo suppression 191, 208 equivalent data 186

key cross-referencing 188, 200, 205 key value in documents 186 mapping canonical ID to native IDs 188 native ID 186 notification of data changes 198 n-way synchronization description 184 example service to build canonical document 210 example service to build native target document 213 one-way synchronization description 184 example service to build canonical document 202 example service to build target native document 206 opening latch 194, 212, 215 preventing circular updates 191 processing overview 185 source, definition 184 targets, definition 184 tasks to implement 196 when source resource uses an adapter 198 database using for document history 159 deadletter queue 20 default client, description 32 default document store, description 49 deleteTrigger service 150 deleting publishable document types 73 triggers 149 delivering documents effect on exactly-once processing statistics 169 specifying destination 102 waiting for a reply 23 when Broker is unavailable 21 Detect duplicates property 159 Developer, valid syntax for naming elements 218 document acknowledgement description 66 storage type relationship 66 document envelope description 64 referenced document type 64 setting field values 92

Publish-Subscribe Developers Guide Version 7.1

225

Index

document history database completed status 160 description of 159 document processing state 160 managing size of 162 overview of 155 preparation of 167 processing status 160 processing when not available 161 reaper interval 162 removing expired entries with a scheduled service 162 removing expired entries with Integration Server Administrator 162 role in duplicate detection 159 sharing by stand-alone servers 167 UUID absence of 160 exceeds max character length 161 existence of 160 document processing changing 138 concurrent 136 description 154 quality of service types 154 resuming 138 retrying for run-time exception 140 selecting 137 serial 133 document resolver service compensating transactions 168 description of 155 exceptions during execution 163, 168 guidelines for 168 purpose of 163 required signature 168 role in duplicate detection 163 document retrieval resuming 138 document status Duplicate 155 FAILED 20, 23, 34, 177, 180 In Doubt 155

STATUS_TOO_MANY_TRIES 23 types of 155 document storage client queue storage impact 67 guaranteed (disk) 66 setting 66 volatile (memory) 66 document type. See publishable document types. documentation additional 10 conventions used 9 feedback 10 using effectively 9 documents delivering and waiting for a reply 104 delivering to a specific destination 19, 101 description 14 publish path 18 publish path for local publishing 34 publish path for request/reply 23 publish path to Broker 19 publish path to outbound document store 21 publish path when Broker unavailable 21 publishing 94 publishing and waiting for a reply 23, 97 publishing locally 95 publishing to Broker 19 publishing when Broker unavailable 21 reply documents 107 replying to 107 retrieving from Broker 27 sending a reply 107 subscribe path 27 subscribe path for delivered documents 30 subscribe path for locally published documents 34 subscribe path for published documents 27 UUID, description 159 UUID, missing 162 validating when published 69 duplicate detection Broker version effect 166 description of 155 document history database 159

Publish-Subscribe Developers Guide Version 7.1

226

Index

document history database unavailable 161 document resolver service 163 document resolver service exceptions 163 overview of methods 156 performance impact 165 redelivery count 158 duplicate detection window impact on exactly-once processing 164 sizing information 167 time drift impact 164 Duplicate documents description of status 155 fate of 157 statistics for 169

exactly-once processing Broker version importance 166 configuring 166 description 154 disabling 168 extenuating circumstances 164 guaranteed storage 67 guidelines 166 overview of 155 performance impact 165 potential for duplicate document processing 164 potential for treating new document as duplicate 165 statistics, clearing 170 statistics, viewing 169

E
echo suppression built-in services for 209 canonical document 209 circular updates 191 closing latch 194, 209, 211, 214 description 191 determining latch status 193, 209, 211, 214 isLatchClosed field, purpose 192 opening latch 194, 209, 212, 215 pub.synchronization.latch closeLatch service 194, 195 isLatchClosed service 193, 194, 195 openLatch service 194, 195 target native document 212 elements, overwriting during document type synchronization 80, 83, 85 Enterprise Integrator, using to edit document types 71 envelope field _env 64 pub.publish:envelope document type 64 published documents 64 restrictions on usage 65 setting values 92 errors, suspending triggers for 53 errorsTo field 93 eventID field, use in duplicate detection 162

F
FAILED document status 20, 23, 34, 177, 180 fatal error handling, configuring 138 field names, limitations in Broker document types 59 filters creating 121, 123 naming restrictions 218 performance impact 122 saved on Integration Server 122 saved on the Broker 122 specifying for a document type 119 where saved 121

G
getCanonicalKey service description 201 example 203 getNativeId service description 201 example 206 guaranteed document delivery, description 154 guaranteed processing, description 67, 154 guaranteed storage description 66 document processing provided 67 guaranteed processing 67

Publish-Subscribe Developers Guide Version 7.1

227

Index

H
History time to live property 162

Only one (XOR) 173 specifying in a trigger 120

I
In Doubt documents description of status 155 fate of 157 statistics for 169 in doubt resolver. See exactly-once processing. In Sync with Broker synchronization status 76 insertXReference service description 201 example 207 Integration Server, description 13 interval, for clearing expired document history entries 162 isLatchClosed field description 192 how used for echo suppression 192 obtaining value from cross-reference table 211, 214 isLatchClosed service description 209 example 211, 214 when to use 193 ISRuntimeException 140

K
keep-alive mode response time (max respone time) 51 retries property (retry count) 51 retry limit (retryCount) 51 key cross-referencing built-in services for 201 cross-reference table fields 189 how used for key cross-referencing 189 purpose of 188 description 188 pub.synchronization.latch closeLatch service 211, 214 isLatchClosed service 211, 214 openLatch service 212, 215 pub.synchronization.xref createXReference service 201, 202, 204 getCanonicalKey service 201, 202, 203 getNativeId service 201, 206 insertXReference service 201, 207 setting up, in source Integration Server 200 setting up, in target Integration Server 205

J
JMS trigger, definition of 9 join conditions activation ID 174 cluster processing 181 description 118, 172 join document, for All (AND) join condition 175 join time-out for All (AND) join condition 128 for Any (OR) join condition 128 for Only one (XOR) join condition 129 setting 128, 129 join types All (AND) condition 172 Any (OR) 172 description 120

L
latching See also echo suppression. description 191 listener notifications, description 65 local publishing effect on exactly-once processing statistics 169 enforcing TTL 52 flag for 96, 99 publish and subscribe paths 34 when trigger queue is full 51

Publish-Subscribe Developers Guide Version 7.1

228

Index

N
naming restrictions for Broker document types 218 for elements 218 for filters 218 native Broker event handling 53 native Broker events disabling document validation 69 native ID adding mapping to canonical ID 204, 207 adding to cross-reference table 207 definition 186 mapping to canonical ID 188 obtaining, for native document 190, 206 obtaining, from cross-reference table 207 service to obtain 201 nativeId field 189 New document description of status 155 fate of 158, 160 None shared document order mode 137 notification of data changes 198 n-way synchronization description 184 example service to build canonical document 210 example service to build target native document 213 example service to receive canonical document 213

OR join. See Any (OR) join. out of sync message 71 outbound document store capacity 51 description 49 disabling use of 52 publishing to 21 overwriting elements during document type synchronization 80, 83, 85 result of 86 skipping during synchronization 86

P
packages updating effect on trigger subscriptions 53 packages, effect of reloading or reinstalling on subscriptions 53 polling notifications, description 65 preprocess errors, for triggers 53 processing status, for document history entries 160 program code conventions in this document 9 pub.flow:getRetryCount service 147 pub.flow:throwExceptionForRetry service 141 pub.publish:deliver service 101 description 92 specifying parameters 102 pub.publish:deliverAndWait service 104 description 92 specifying parameters 105 pub.publish:documentResolverSpec service 168 pub.publish:getRedeliveryCount service 159 pub.publish:publish service 94 description 92 example 204 pub.publish:publishAndWait service 97 description 92 specifying parameters 98 pub.publish:reply service description 92 specifying parameters 109 pub.publish:waitForReply service 92, 100, 107 pub.trigger:createTrigger service 121 pub.trigger:deleteTrigger service 150

O
objectId field 189 one-way synchronization description 184 example service to build canonical document 202 example service to build target native document 206 example service to receive canonical document 206 Only one (XOR) join description 120, 173 satisfying 177 subscribe path 177 time-out 129 openLatch service description 209 example 212, 215

Publish-Subscribe Developers Guide Version 7.1

229

Index

publication properties setting 66 storage type 66 time-to-live 68 validate when published 70 publishable document types adapter notifications 65 assigning storage type 67 broken references 72 canonical document 200 creating from Broker document type 59, 60 creating from existing IS document type 57 deleting 73 description 14, 56 disk storage 66 editing considerations 71 filter for 119 guaranteed storage 66 making publishable 57 making unpublishable 72 memory storage 66 modifying 71 out of sync message 71 overwriting elements when synchronizing 85 publication properties storage type 66 time-to-live 68 removing subscriptions on reload or reinstall 53 reverting to IS document types 72 synchronization status Created Locally 76 description 75 In Sync with Broker 76 Removed from Broker 76 Updated Both Locally and on the Broker 76 Updated Locally 75 Updated on Broker 75 synchronizing access permissions 80, 83 importance of 77 in a cluster 85 many at one time 81 one at a time 80

overwriting elements 75, 80, 85 pull from Broker 77 purpose of 75 push to Broker 77 result of 78 skip 77 testing 86 time-to-live 68, 69 validtion of 69 volatile storage 66 with pre-existing _env fields 65 Publishable Locally Only value, for Broker doc type property 64 publish-and-subscribe model adapter notifications 15 building 40 canonical documents 16 description 12 documents 14 publishable document types 14 services 15 triggers 15 Publisher shared document order mode 134 publishing documents asynchronous request/reply flag 100, 106 broadcasting to all subscribers 94 delay until service success flag 96, 103, 111 delaying until top-level service success 96, 103, 111 delivering 101 delivering and waiting 104 enforcing TTL 52 issuing request document 97, 104 local publishing flag 96, 99 locally 34, 95 maximum documents published on success 51 publishing and waiting for a reply 23, 97 replying to a request 107 retrieving reply document 100 to a Broker 95 to outbound document store 21 validating on publish 69 when Broker is unavailable 21 when trigger queue is full 51 without a configured Broker 18

Publish-Subscribe Developers Guide Version 7.1

230

Index

publishing path local publishing 34 overview 18 request/reply documents 23 to Broker 19 when Broker is unavailable 21 publishing services blocking 51 maximum published documents 51 pub.publish:deliver 92 pub.publish:deliverAndWait 92 pub.publish:publish 92 pub.publish:publishAndWait 92 pub.publish:reply 92 pub.publish:waitForReply 92 Pull from Broker synchronization action 77 Push to Broker synchronization action 77

Q
queues. See acknowledgement queue, deadletter queue, trigger queues.

R
reaper interval, for document history database 162 receivedDocumentEnvelope field 108 redelivery count description of 155 greater than zero 158 retrieving 159 role in duplicate detection 158 undefined (-1) 158 zero (0) 158 refill level, for trigger queues 130 Removed from Broker synchronization status 76 removing expired entries, from document history database 162 renaming, publishable document types 72 reply documents arriving after request expires 26 envelope 108 many for a single request 101 retrieving 100, 107 storage type 26, 107 waiting for 100, 107

replying to a request document 107 replyTo field 93 request document, publishing 97, 104 request/reply client, sessions for 50 request/reply model asynchronous 23 asynchronous flag 100, 106 building service 97, 104 description 23, 97, 104 multiple replies 101 no replies 101 overview of process 24 replyTo field importance 93 specifying reply document type 99, 106 synchronous 23 requirements for retrying trigger services 141 for trigger services 115 for valid triggers 117 resource monitoring service definition of 222 requirements 222 resource monitoring service, execution interval 52 retries configuring for trigger services 140 description of for triggers 140 triggers and services 146 retrieving documents from a Broker 27 redelivery count 159 retry failure definition of 141 Suspend and retry later option 143 Throw exception option 142 Retry failure behavior property 146 retry limit setting to zero 147 specifying for trigger service 140 retry properties, for triggers 144 rules, for valid triggers 117 run-time exception, description 140

Publish-Subscribe Developers Guide Version 7.1

231

Index

S
scheduled service, for managing document history database 162 serial processing description 133 in clusters 134 serial triggers fatal error handling 138 server threads, acknowledgement queue 133 service retries, and trigger retries 146 services See also built-in services, publishing services, trigger services. description 15 echo suppression 209 specifying in a trigger 119 Shared Document Order mode None 137 Publisher 134 simple conditions, description 118 statistics, for exactly-once processing 169 STATUS_TOO_MANY_TRIES document status 23 Storage type property 67 storage types document vs client queue 67 specifying for publishable document types 67 subscribe path All (AND) join condition 174 Any (OR) join condition 173 delivered documents 30 join documents 173 locally published documents 34 Only one (XOR) join condition 177 overview 27 published documents 27 subscriptions creating 118 deadletters 20 Suspend and retry later option 141, 143 Sync All Document Types dialog box 81 Sync All Out-of-Sync Document Types dialog box 81 synchronization action Pull from Broker 77, 78, 79 Push to Broker 77, 78, 79

result of 78 Skip 77 synchronization of resources 194, 198 closing latch 211, 214 creating canonical ID 204 creating trigger service that builds canonical document 202 creating trigger service that builds target native document 205 creating trigger to subscribe to canonical document 205 creating trigger to subscribe to notification document 202 cross-reference table used for key cross-referencing 189 determining whether latch is open or closed 193, 211, 214 determining whether to update an object 193 echo suppression 191, 208 equivalent data 186 key cross-referencing 188, 200, 205 key value in documents 186 mapping canonical ID to native IDs 188 native ID 186 n-way synchronization description 184 example service to build canonical document 210 example service to build native target document 213 one-way synchronization description 184 example service to build canonical document 202 example service to build target native document 206 opening latch 194, 212, 215 preventing circular updates 191 processing overview 185 source, definition 184 targets, definition 184 tasks to implement 196 synchronization status after changing Brokers 76 Created Locally 76, 78, 79 for publishable document types 75 In Sync with Broker 76, 79 Removed from Broker 76, 79 Updated Both Locally and on the Broker 76, 78 Updated Locally 75, 76, 78 Updated on Broker 75, 78

Publish-Subscribe Developers Guide Version 7.1

232

Index

synchronizing publishable document types access permissions needed 80, 83 actions 76 Created Locally status 76 importance of 77 In Sync with Broker status 76 overwriting elements 80, 83, 85 result of overwriting 86 result of skipping 86 Pull from Broker action 77 purpose of 75 Push to Broker action 77 Removed from Broker status 76 result of 78 Skip action 77 synchronization status 75 synchronizing a single document type 80 synchronizing document types in a cluster 85 synchronizing multiple document types 81 Updated Both Locally and on the Broker status 76 Updated Locally status 75, 76 Updated on Broker status 75 when to 75 synchronous request/reply, description 23, 97, 104 syntax for fields in Broker document types 218

T
tag field, in request/reply 24, 26, 100, 106 territories, switching 48 testing publishable document types 86 triggers 150 Throw service exception option 141, 142 time drift description of 165 impact on exactly-once processing 164 time to live property 68 specifying for publishable document types 69 trackID field, use in duplicate detection 162 transient error handling, configuring 140 transient error, description 140

trigger document store description 49 saved in memory 28 saved on disk 32, 35 storage type 33, 49 trigger queues capacity 130 description 130 handling documents when full 51 refill level 130 trigger services auditing 116 create canonical document 202 description 115 infinite retry loop 145 infinite retry loop, escaping 148 performance 147 requirements 115 retry count, retrieving 147 retry requirements 141 retrying 140 trigger retries and service retries 146 user account for invoking 49 XSLT services 119 triggers acknowledgement queue size 132 adding conditions 125 capacity 130 changing condition order 126 configuring exactly-once processing 166 configuring retries 140 creating 118 creating filters 123 data synchronization source 202 data synchronization target 205 deleting 149 deleting document type subscriptions 53 deleting in a cluster 150 description 15, 114 disabling 126 document processing mode changing 138 concurrent 136

Publish-Subscribe Developers Guide Version 7.1

233

Index

selecting 137 serial 133 enabling 127 exactly-once processing, disabling 168 exactly-once processing, statistics 169 fatal error handling 138 guidelines for creating 117 join condition 118 modifying 149 monitoring interval 52 multiple conditions 123 naming 118 overview of building process 114 refill level 130 removing subscriptions during reload or reinstall 53 retry failure 141 retry properties 144 retry requirments 141 retry, setting to 0 147 retrying 53, 140 service requirements 115 setting properties 126 simple condition 118 specifying document type filter 119 specifying join type 120 specifying permissions 120 specifying publishable document type 119 specifying trigger service 119 subscribe to canonical documents 186 suspending 53, 143 testing 150 testing a join condition 152 transient error handling 140 trigger service retry 140 user account for invoking service 49 valid trigger requirements 117 XSLT services 119 troubleshooting information 10 typographical conventions in this document 9

Updated Both Locally and on the Broker synchronization status 76 Updated Locally synchronization status 75 Updated on Broker syncrhonization status 75 Use history property 159 user account, for invoking trigger services 49 UUID (Universally Unique Identifier) absence of 162 assigning to two documents 165 description of 159 documents without 162 role in duplicate detection 160

V
Validate when published property 70 validation, requirements for triggers 117 volatile storage at-most-once processing 66 description 66 reply documents 107

W
waitForReply service 100, 107 waiting for reply 100, 107 watt.server.broker.producer.multiclient 50 watt.server.broker.replyConsumer.fetchSize 50 watt.server.broker.replyConsumer.multiclient 50 watt.server.broker.replyConsumer.sweeperInterval 50 watt.server.brokerTransport.dur 50 watt.server.brokerTransport.max 51 watt.server.brokerTransport.ret 51 watt.server.cluster.aliasList 51 watt.server.control.maxPersist 51 watt.server.control.maxPublishOnSuccess 51, 97, 103 watt.server.dispatcher.comms.brokerPing 51 watt.server.dispatcher.join.reaperDelay 51 watt.server.idr.reaperInterval 51, 162 watt.server.publish.local.rejectOOS 51 watt.server.publish.useCSQ 52 watt.server.publish.usePipelineBrokerEvent 52 watt.server.publish.validateOnIS 70 watt.server.trigger.interruptRetryOnShutdown 52, 148 watt.server.trigger.keepAsBrokerEvent 52

U
undefined redelivery count 158 Univerally Unique Identifier. See UUID.

Publish-Subscribe Developers Guide Version 7.1

234

Index

watt.server.trigger.local.checkTTL 52 watt.server.trigger.managementUI.excludeList 52 watt.server.trigger.monitoringInterval 52 watt.server.trigger.preprocess.suspendAndRetryOnError 53, 161, 163 watt.server.trigger.removeSubscriptionOnReloadOrReinstall 53 watt.server.xref.type 53 webMethods Broker 13 webMethods Integration Server 13

X
XOR join. See Only one (XOR) join. XSLT service, and triggers 119

Publish-Subscribe Developers Guide Version 7.1

235

Index

Publish-Subscribe Developers Guide Version 7.1

236