Title Page

Integration Server Version 7.1 webMethods Integration Server JMS

Client Developer’s Guide
Copyright
&  Docu‐
ment ID

Cerebra, Glue, Infravio X‐Broker, Infravio X‐Registry, Infravio, My webMethods Server, My webMethods, webMethods Access, webMethods Administrator, 
webMethods Broker, webMethods Central Configuration, webMethods Dashboard, webMethods Designer, webMethods Developer, webMethods Fabric, 
webMethods Glue, webMethods Infrastructure Data Collector, webMethods Infravio X‐Broker, webMethods Infravio X‐Registry, webMethods Installer, 
webMethods Integration Server, webMethods logo, webMethods Mainframe, webMethods Manager, webMethods Modeler, webMethods Monitor, 
webMethods Optimize for Infrastructure, webMethods Optimize for Process, webMethods Optimize, webMethods Portal, webMethods Process Engine, 
webMethods Servicenet, webMethods Task Engine, webMethods Trading Networks, webMethods Workflow, and webMethods are either registered 
trademarks or trademarks of webMethods, Inc.
Acrobat, Acrobat, and Reader are registered trademarks of Adobe Systems Incorporated.  Amdocs and ClarifyCRM are registered trademarks of Amdocs.  
Ariba is a registered trademark of Ariba, Inc.  BEA, BEA WebLogic Server, Jolt, and Tuxedo are registered trademarks, and BEA WebLogic Platform is a 
trademark of BEA Systems, Inc.  Action Request System, BMC Software, PATROL, and Remedy are registered trademarks of BMC Software, Inc.  BroadVision 
is a registered trademark of BroadVision, Inc.  Chem eStandards and CIDX are trademarks of CIDX, The Chemical Industry Data Exchange.  SiteMinder and 
Unicenter are registered trademarks of CA, Inc.  PopChart is a registered trademark of CORDA Technologies, Inc.  Kenan and Arbor are registered trademarks 
of Alcatel‐Lucent.  Data Connection and SNAP‐IX are registered trademarks of Data Connection Corporation.  D&B and D‐U‐N‐S are registered trademarks of 
Dun & Bradstreet Corporation.  Eclipse is a trademark of Eclipse Foundation, Inc.  Entrust is a registered trademark of Entrust, Inc.  papiNet is a registered 
trademark of the European Union and the United States.  Financial Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd.  
UCCnet and eBusinessReady are registered trademarks, and 1SYNC and Transora are trademarks of GS1 US.  Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐
RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company.  i2 is a registered trademark of i2 Technologies, Inc.  AIX, AS/400, CICS, ClearCase, DB2, 
Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and 
z/OS are registered trademarks; and Communications System for Windows NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM 
Corporation.   InnoDB is a trademark of Innobase Oy.  Itanium is a registered trademark of Intel Corporation.  Linux is a registered trademark of Linus 
Torvalds.  W3C is a registered trademark, and X Window System is a trademark of the Massachusetts Institute of Technology.  MetaSolv is a registered 
trademark of Metasolv Software, Inc.  ActiveX, Microsoft, Outlook, Visual Basic, Visual SourceSafe, Windows, Windows NT, and Windows Server are 
registered trademarks of Microsoft Corporation.   Six Sigma is a registered trademark of Motorola, Inc.  Firefox and Mozilla are registered trademarks of the 
Mozilla Foundation.  MySQL is a registered trademark of MySQL AB.  nCipher is a trademark of nCipher Corporation Ltd.   Eclipse is a trademark of Eclipse 
Foundation, Inc.  Entrust is a registered trademark of Entrust, Inc.  papiNet is a registered trademark of the European Union and the United States.  Financial 
Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd.  UCCnet and eBusinessReady are registered trademarks, and 1SYNC and 
Transora are trademarks of GS1 US.  Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company.  i2 is a 
registered trademark of i2 Technologies, Inc.  AIX, AS/400, CICS, ClearCase, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, 
OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and z/OS are registered trademarks; and Communications System for Windows 
NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM Corporation.  InnoDB is a trademark of Innobase Oy.  Itanium is a registered 
trademark of Intel Corporation.   Teradata is a registered trademark of NCR Corporation. Netscape is a registered trademark of Netscape Communications 
Corporation.  ServletExec is a registered trademark, and New Atlanta is a trademark of New Atlanta Communications, LLC.  SUSE is a registered trademark 
of Novell, Inc.  Appia is a registered trademark and Javelin Technologies is a trademark of NYFIX, Inc.  CORBA is a registered trademark of Object 
Management Group, Inc.  JD Edwards, OneWorld, Oracle, PeopleSoft, Siebel, and Vantive are registered trademarks; and Infranet, PeopleSoft Pure Internet 
Architecture, Portal, and WorldSoftware are trademarks of Oracle Corporation.  Perforce is a trademark of Perforce Software.  JBoss and Red Hat are 
registered trademarks of Red Hat, Inc.  PIP and RosettaNet are trademarks of RosettaNet, a non‐profit organization.   SAP and R/3 are registered trademarks 
of SAP AG.  PVCS is a registered trademark of Serena Software, Inc.  SWIFT and SWIFTNet are registered trademarks of Society for Worldwide Interbank 
Financial Telecommunication SCRL.  SPARC and SPARCStation are registered trademarks of SPARC International, Inc.  BAAN and SSA are registered 
trademarks; and SSA Global is a trademark of SSA Global Technologies, Inc.  EJB, Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, Sun, and 
Sun Microsystems are registered trademarks; and Java Naming and Directory Interface, JavaServer Pages, SOAP with Attachments API for Java, and SunSoft 
are trademarks of Sun Microsystems, Inc.  Sybase is a registered trademark of Sybase, Inc.  VERITAS is a registered trademark, and VERITAS Cluster Server is 
a trademark of Symantec Corporation.  UNIX is a registered trademark of The Open Group.  Unicode is a trademark of Unicode, Inc.  VeriSign is a registered 
trademark of Verisign, Inc. 
Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG. 
Other product and company names mentioned herein may be the trademarks of their respective owners.
Copyright © 2007 webMethods, Inc. All rights reserved.
Copyright © 2007 Software AG and/or its suppliers, Uhlandstrasse 12, 64297 Darmstadt, Germany. All rights reserved.

Document ID: DEV-JMS-DG-71-20070928

 Contents

Contents

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1. Configuring Integration Server for JMS Messaging . . . . . . . . . . . . . . . . . . . . . 9

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Working with JNDI Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Creating a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Editing a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Deleting a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Performing a Test Lookup for a JNDI Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Working with JMS Connection Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Creating a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Specifying a Retry Interval for Failed Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Specifying a Keep Alive Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Editing a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Enabling and Disabling a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Deleting a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Creating Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Load Balancing Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2. JMS Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

JMS Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Messaging Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Point-to-point (PTP) Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Publish-Subscribe Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Durable Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Non-durable Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
JMS API Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Types of Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Connection Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 3

 Contents

Message Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Message Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 3. Sending and Receiving JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

The JMS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Sending a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
How to Send a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Sending a JMS Message and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
How to Send a Request Message and Wait for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Replying to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
How to Send a Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Receiving a JMS Message Using Built-In Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
How to Actively Receive a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Sending a JMS Message as Part of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
How to Send a JMS Message within a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Setting Properties in a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Assigning an Activation to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Setting the UUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 4. Working with JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Overview of Building a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
JMS Trigger Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Creating a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Creating a Message Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Creating a Local Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Enabling or Disabling a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Setting an Acknowledgment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Setting a Join Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Join Time-outs for All (AND) Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Join Time-outs for Only One (XOR) Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Setting a Join Time-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Specifying the Execution User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Specifying Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Serial Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Concurrent Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Message Processing and Message Consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Processing Messages in Batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Configuring Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 4

 Contents

Handling Fatal Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Handling Transient Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Configuring Retry Behavior for Trigger Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Service Requirements for Retrying a Trigger Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Handling Retry Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Overview of Throw Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Overview of Suspend and Retry Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Configuring Transient Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Generating Events for JMS Retrieval Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Debugging a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Building JMS Triggers with Multiple Routing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Chapter 5. Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

What Is a Transacted JMS Trigger? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Overview of Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Prerequisites for a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Properties for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Steps for Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Handling Fatal Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Handling Transient Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Overview of Recover Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Overview of Suspend and Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring Transient Error Handling for a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . 85

Chapter 6. Exactly-Once Processing for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Duplicate Detection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Delivery Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
What Happens When the Document History Database Is Not Available? . . . . . . . . . . . . . 94
Managing the Size of the Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Document Resolver Service and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Considerations for Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Configuring Exactly-Once Processing for a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Disabling Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 5

 Contents

Chapter 7. Managing JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Controlling Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Viewing Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Increasing or Decreasing Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Enabling, Disabling, and Suspending JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Appendix A. JMS Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
watt.server.jms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Appendix C. Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Implicit and Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Implicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 6

 About This Guide

About This Guide

The webMethods Integration Server JMS Client Developer’s Guide is designed for the 
developer who is responsible for developing solutions that use webMethods Integration 
Server to send and receive messages using Java Messaging Service (JMS). 
This guide does the following:
Explains how to establish connections to one or more JMS providers. 

Describes how to build a JMS trigger to use for receiving JMS messages.

Explains how to build services that send and receive JMS messages using built‐in 
services. 
This guide assumes that you are familiar with the following:
Basic concepts of webMethods architecture and terminology.

Usage of webMethods Developer to create elements and build services. 

General knowledge of programming, the Java programming language, and the JMS 
API. 

Note: An in‐depth treatment of messaging architecture is beyond the scope of this guide, 
but is available elsewhere. For information about the JMS API, please refer to the Java 
Message Service, Version 1.1 specification on the Sun Microsystems Java Message Service 
(JMS) Web site.

Note: With webMethods Developer, you can create Broker/local triggers and JMS triggers. 
A Broker/local trigger is trigger that subscribes to and processes documents 
published/delivered locally or to the Broker. A JMS trigger is a trigger that receives 
messages from a destination (queue or topic) on a JMS provider and then processes those 
messages. This guide discusses development and use of JMS triggers only. Where the term 
triggers appears in this guide, it refers to JMS triggers. For information about creating 
Broker/local triggers, see the Publish‐Subscribe Developer’s Guide.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 7

 About This Guide

Document Conventions

Convention Description
Bold Identifies elements on a screen.
Italic Identifies variable information that you must supply or change 
based on your specific situation or environment. Identifies terms the 
first time they are defined in text. Also identifies service input and 
output variables.
Narrow font Identifies storage locations for services on the webMethods 
Integration Server using the convention folder.subfolder:service.
Typewriter Identifies characters and values that you must type exactly or 
font messages that the system displays on the console.
UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously 
are joined with the “+” symbol.
\ Directory paths use the “\” directory delimiter unless the subject is 
UNIX‐specific.
[ ] Optional keywords or values are enclosed in [ ]. Do not type the [ ] 
symbols in your own code.

Additional Information
The webMethods Advantage Web site at http://advantage.webmethods.com provides you 
with important sources of information about webMethods products:
Troubleshooting Information. The webMethods Knowledge Base provides 
troubleshooting information for many webMethods products. 
Documentation Feedback. To provide feedback on webMethods documentation, go to 
the Documentation Feedback Form on the webMethods Bookshelf.
Additional Documentation. Starting with 7.0, you have the option of downloading the 
documentation during product installation to a single directory called 
“_documentation,” located by default under the webMethods installation directory. In 
addition, you can find documentation for all webMethods products on the 
webMethods Bookshelf.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 8

Chapter 1. Configuring Integration Server for JMS
Messaging

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Working with JNDI Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Working with JMS Connection Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Creating Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Load Balancing Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 9

 1. Configuring Integration Server for JMS Messaging

Overview
To configure Integration Server for JMS messaging, you need to:
Create one or more JNDI provider aliases to specify where Integration Server can look 
up administered objects when it needs create a connection to JMS provider or specify 
a destination for sending or receiving messages.
Create one or more connection aliases that encapsulate the properties that Integration 
Server needs to create a connection with the JMS provider.
Integration Server also includes various server configuration properties that you can use 
to change the default server behavior. For a list of server configuration parameters related 
to JMS, see Appendix A, “JMS Server Configuration Parameters”. 

Working with JNDI Providers

Each JMS provider can store JMS administered objects in a standardize namespace called 
the Java Naming and Directory Interface (JNDI). JNDI is a Java API that provides naming 
and directory functionality to Java applications.
As the JMS client, Integration Server uses a JNDI provider alias to encapsulate the 
information needed to look up an administered object. When you create a JMS connection 
alias, you can specify the JNDI provider alias that Integration Server should use to look up 
administered objects (i.e., Connection Factories and Destinations). 

Note: If you connect directly to the webMethods JMS Provider using native webMethods 
API, you do not need to use a JNDI provider. Instead, you can create Destinations directly 
on the webMethods Broker. You do not need to create Connection Factories if you use the 
native webMethods API. 

Creating a JNDI Provider Alias

Use the following procedure to create an alias to a JNDI provider. 

To create a JNDI provider alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JNDI Settings.
4 Click Create JNDI Provider Alias.
5 Specify the following information for the JNDI provider alias:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 10

 1. Configuring Integration Server for JMS Messaging

In this field... Specify...

JNDI Alias Name The alias name that you want to assign to this JNDI provider. 

Description A description for this JNDI alias. 
Predefined JNDI The JNDI template that you want to use. 
Templates
The JNDI templates provide information that you can use to 
complete alias configuration for a specific provider. 

Note: After you create a JNDI provider, Integration Server 
Administrator displays Current Settings as the value of the 
Predefined JNDI Templates field. This indicates that Integration 
Server uses the currently specified settings for the JNDI 
provider alias. 

Initial Context The class name of the JNDI provider. The JNDI provider uses 

Factory the initial context as the starting point for resolving names for 
naming and directory operations. 
If you selected a pre‐defined JNDI template, Integration Server 
displays the initial context factory for the provider.
Provider URL The URL of the initial context for sessions with the JNDI 
provider. The URL specifies the JNDI directory in which the 
JNDI provider stores JMS administered objects.
If you selected a pre‐defined JNDI template, replace the 
placeholder information in brackets << >> with information 
specific to your configuration. 
Security Principal The principal name, or user name supplied by Integration 
Server to the JNDI provider, if the provider requires one for 
accessing the JNDI directory
For information about whether or not the JNDI provider 
requires security principal information, consult the product 
documentation for the JNDI provider. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 11

 1. Configuring Integration Server for JMS Messaging

In this field... Specify...

Security The credentials, or password, that Integration Server provides 
Credentials to the JNDI provider, if the provider requires security 
credentials to access the JNDI directory.
For information about whether or not the JNDI provider 
requires security credentials, consult the product 
documentation for the JNDI provider. 
Other Properties Any additional properties the JNDI provider requires for 
configuration. For example, you might need to specify the 
classpath for any additional .jar or class files that the JNDI 
provider needs to connect to the JNDI. 
When you select a pre‐defined JNDI template, Integration 
Server populates this field with any additional properties and 
placeholder information required by the JNDI provider. 
For more information about additional properties or classes 
required by a JNDI provider and the location of those files, see 
the product documentation for the JNDI provider. 

6 Click Save Changes.

Editing a JNDI Provider Alias

Use the following procedure to edit an existing JNDI provider alias. 

To edit a JNDI provider alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JNDI Settings.
4 In the JNDI Provider Alias Definitions list, select the JNDI provider alias that you 
want to edit. Integration Server Administrator displays details about the JNDI 
provider alias.
5 Click Edit JNDI Provider Alias. 
6 Edit the properties of the JNDI provider alias. 
For more information about the fields, see “To create a JNDI provider alias” on 
page 10. 
7 Click Save Changes.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 12

 1. Configuring Integration Server for JMS Messaging

Deleting a JNDI Provider Alias

Use the following procedure to delete a JNDI provider alias. 

Important! When you delete a JNDI provider alias, any service or JMS trigger that uses a 
JMS connection alias that relies on the JNDI provider alias will fail.

To delete a JNDI provider alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JNDI Settings.

4 Locate the alias you want to delete and click the   icon in the Delete field. Integration 
Server displays a dialog box that prompts you to verify your action. Click OK to verify 
that you want to delete the JNDI provider alias.

Performing a Test Lookup for a JNDI Provider

Using Integration Server Administrator, you can perform a test lookup for a JNDI 
provider alias. The test lookup lists all of the Objects in the JNDI namespace referenced by 
the alias. 

To perform a test lookup for a JNDI provider

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JNDI Settings.

4 Locate the alias you want to delete and click the   icon in the Test Lookup field. 

Integration Server returns a list of the Objects located in the JNDI namespace. 

Working with JMS Connection Aliases

A JMS connection alias specifies the information that Integration Server needs to establish 
an active connection between Integration Server and the JMS provider. Integration Server 
uses a JMS connection alias to send messages to and receive messages from the JMS 
provider. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 13

 1. Configuring Integration Server for JMS Messaging

Creating a JMS Connection Alias

When you create a JMS connection alias, keep the following points in mind:
You can use JNDI to retrieve administered objects (Connection Factories and 
Destinations) and then use the Connection Factory to create a connection. If you 
intend to use a JNDI provider, you need to configure one or more JNDI provider 
aliases before creating a JMS connection alias. 
– or –
You can use the native webMethods API to create the connection directly on the 
webMethods JMS Provider. You can also create Destinations at the webMethods 
Broker. If you intend to use the native webMethods API, you do not need to configure 
a JNDI provider alias. 
Each connection alias has an associated transaction type. Within Integration Server, 
certain functionality must be completed within a non‐transacted session. For example, 
to use Integration Server to send or receive large message streams, you must specify a 
JMS connection alias whose transaction type is set to NO_TRANSACATION. For 
more information about transaction types, see “Transaction Types” on page 118.

To create a JMS connection alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JMS Settings.
4 Click Create JMS Connection Alias.
5 Set the following General Settings for the JMS connection alias:

For this field... Specify...

Connection Alias Name of the connection alias. Each connection alias represents 

Name a connection factory to a specific JMS provider. 
Description A description of the JMS connection alias. 
Transaction Type Whether sessions that use this JMS connection alias will be 
transacted. 
Select... To...

NO_TRANSACTION Indicate that sessions that use this 
JMS connection alias are not 
transacted.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 14

 1. Configuring Integration Server for JMS Messaging

For this field... Specify...

LOCAL_TRANSACTION Indicate that sessions that use this 
JMS connection alias are part of a local 
transaction. 
XA_TRANSACTION Indicate that sessions that use this 
JMS connection alias are part of an XA 
transaction. 
Connection Client The JMS client identifier associated with the connections 
ID established by this JMS connection alias. 
User (optional) User name needed to acquire a connection from the 
connection factory. 
For more information about whether or not the JMS provider 
requires a user name and password to obtain a connection, 
refer to the product documentation for the JMS provider. 
Password Password needed to acquire a connection from the connection 
(optional) factory. 
For more information about whether or not the JMS provider 
requires a user name and password to obtain a connection, 
refer to the product documentation for the JMS provider.

6 In Create Connection Using list, select one of the following to indicate how administered 

objects (connection factories and destinations) will be looked up:
If you intend to use a JNDI provider, select JNDI Lookup and proceed to step 7.
If you intend to use the native webMethods API to create the connection directly 
on the webMethods JMS Provider, select Native webMethods API and proceed to 
step 8.
7 If you selected JNDI Lookup in step 6, do the following in the remaining fields under 
Connection Protocol Settings:
a In the JNDI Provider Alias Name field, select the alias to the JNDI provider that you 
want to this JMS connection alias to use to look up administered objects. For 
information about creating a JNDI provider alias, see “Creating a JNDI Provider 
Alias” on page 10.
b In the Connection Factory Lookup Name field, specify the lookup name for the 
connection factory that you want to use to create a connection to the JMS provider 
specified in this JMS connection alias. 
8 If you selected Native webMethods API in step 6, do the following in the remaining fields 
under Connection Protocol Settings:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 15

 1. Configuring Integration Server for JMS Messaging

a Configure the connection to the Broker Server that you want to use as the 
webMethods JMS Provider for this JMS connection alias. For information about 
configuring a connection to a Broker Server, see the webMethods Integration Server 
Administrator’s Guide.
b In the Client Group field, specify the name of the client group to which you want 
Integration Server to belong when it acts as a JMS client. The client group that you 
specify must already exist on the Broker Server. The default is IS‐JMS. 
c In the Broker List field, specify a comma delimited list of Broker Servers on which 
the connection between the Integration Server (acting as the JMS client) and the 
webMethods JMS Provider can exist. This provides connection failover. If a 
connection failure occurs to the first Broker Server in the list, a connection attempt 
will be made to the next Broker Server listed. Use the following format for each 
Broker:
{Broker Name]@<host>[:port]

Note: If a connection to a Broker Server is already configured (via Settings >

Messaging > Broker Settings), Integration Server populates the fields under 
Connection Protocol Settings with information about that Broker Server. If that 
Broker Server functions as the webMethods JMS Provider, you may not need to 
edit any information. However, make sure that the Client Group field specifies 
the client group to which you want Integration Server to belong when it functions 
as a JMS client.

9 Under Advanced Settings, specify the following information for the JMS connection 
alias:

For this field... Specify...

Class Loader The name of the class loader that you want to use with this 

JMS connection alias. Integration Server will use the specified 
class loader when performing certain activities with the JMS 
connection alias (send a message, receive a message, create a 
connection, create a destination, etc.)
By default, Integration Server uses the server class loader. 
However, you can specify the class loader for a package 
instead. This may be helpful when working with third party 
JMS providers. For example, you might place the third party 
jars needed for each JMS provider in separate packages, 
specifically, in the 
IntegrationServer_directory/packageName/code/jars directory. 
This can help prevent conflicts between the jars required for 
different JMS providers. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 16

 1. Configuring Integration Server for JMS Messaging

For this field... Specify...

Maximum CSQ Size The maximum number of messages that can exist in the client 

(number of side queue for this JMS connection alias. Integration Server 
documents) writes messages to the client side queue if the JMS provider is 
not available when messages are sent. Each JMS connection 
alias has its own client side queue. 
Specify ‐1 if you want the client side queue to be able to 
contain an unlimited number of messages. That is, specify ‐1 if 
you do not want to set a maximum limit. 
If you specify 0, Integration Serverwill not write messages to 
the client side queue for this JMS connection alias. 
Drain CSQ in Order Whether Integration Server drains the client side queue by 
sending the messages to the JMS provider in the same order in 
which Integration Server placed the messages in the client side 
queue. 
Select the check box if you want Integration Server to send 
messages from the client side queue in the same order in 
which Integration Server originally placed the messages in the 
client side queue. 
When the Drain CSQ in Order check box is selected, after the 
connection to the JMS provider is re‐established, Integration 
Server continues to write new messages to the client side 
queue until the client side queue is completely drained. If the 
Drain CSQ in Order check box is not selected, after the connection 
to the JMS provider is re‐established, Integration Server sends 
new messages directly to the JMS provider while it drains the 
client side queue. 

Note: You can also specify the number of messages Integration 
Server retrieves from the client side queue for delivery to the 
JMS provider at one time. By default, Integration Server sends 
25 messages at a time. For more information about the 
watt.server.jms.csq.batchProcessingSize property, see 
Appendix A, “JMS Server Configuration Parameters”. 

10 Click Save Changes.

Specifying a Retry Interval for Failed Connections

When a connection between Integration Server and the JMS provider fails, Integration 
Server attempts to re‐establish the connection automatically after a 20 second delay. You 
can configure how long Integration Server waits between attempts to re‐establish the 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 17

 1. Configuring Integration Server for JMS Messaging

connection by changing the value of the watt.server.jms.connection.retryPeriod 
property. For more information about this property, see Appendix A, “JMS Server 
Configuration Parameters”. For information about modifying extended settings using 
Integration Server Administrator, see the webMethods Integration Server Administrator’s 
Guide.

Specifying a Keep Alive Interval

Integration Server periodically pings the JMS provider to keep the connection between the 
Integration Server and the JMS provider active. The ping acts as a keep‐alive request. By 
default, Integration Server pings the JMS provider every 300 seconds. You can configure 
how frequently Integration Server pings the JMS provider by changing the value of the 
watt.server.jms.connection.pingPeriod property. For more information about this 
property, see Appendix A, “JMS Server Configuration Parameters”. For information about 
modifying extended settings using Integration Server Administrator, see the webMethods 
Integration Server Administrator’s Guide.

Editing a JMS Connection Alias

After you create a JMS connection alias, you might need to modify properties of the alias. 
For example, you might want to reduce the amount of memory that the client side queue 
can occupy by decreasing the maximum number of messages that can be placed in the 
client side queue. You can edit any properties of a JMS connection alias with the exception 
of the alias name and the method used to look up administered objects (Create Connection
Using field).
You must disable a JMS connection alias before you can edit it.

To edit a JMS connection alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JMS Settings.
4 In the JMS Connection Alias Definitions list, select the JMS connection alias that you 
want to edit. Integration Server Administrator displays details about the connection 
alias.
5 Click Edit JMS Connection Alias. 
6 Edit the properties of the connection alias. For more information about the fields, see 
“To create a JNDI provider alias” on page 10. Note that the Connection Alias Name and 
Create Connection Using fields cannot be modified. 
7 Click Save Changes.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 18

 1. Configuring Integration Server for JMS Messaging

Enabling and Disabling a JMS Connection Alias

When a JMS connection alias is enabled, Integration Server can use the alias to obtain 
connections, send messages, and receive messages on behalf of services and JMS triggers. 
When a connection alias is disabled, Integration Server stops all JMS triggers that use the 
alias. Additionally, any services that use a disabled JMS connection alias to send or receive 
messages will end in error. 

To enable or disable a JMS connection alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JMS Settings.
4 In the JMS Connection Alias Definitions list, disable the alias if it is not already 
disabled.
5 In the JMS Connection Alias Definitions list, do one of the following in the Enabled 
column:
Click No if the alias is disabled and you want to enable it. 
If Integration Server cannot enable the alias, it displays a message under the alias 
indicating why Integration Server cannot enable the alias. 
Click Yes if the alias is enabled and you want to disable it.

Deleting a JMS Connection Alias

Before you delete a JMS connection alias, make sure of the following:
The JMS connection alias is disabled.

No services or JMS triggers rely on the JMS connection alias. If a JMS trigger uses a 
JMS connection alias, Integration Server will prevent the JMS connection alias from 
being deleted 

To delete a JMS connection alias

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging. 
3 Under JMS Configuration, click JMS Settings.
4 In the JMS Connection Alias Definitions list, disable the alias if it is not already 
disabled.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 19

 1. Configuring Integration Server for JMS Messaging

5 Locate the alias you want to delete and click the   icon in the Delete field. Integration 
Server displays a dialog box that prompts you to verify your action. Click OK to verify 
that you want to delete the JMS connection alias.

Creating Administered Objects

The JMS provider that you select should provide you with the tools to create and 
configure administered objects in a JNDI namespace. Integration Server cannot be used to 
create and configure administered objects. For more information about working with 
administered objects, refer to the product documentation for your chosen JMS provider. 

Load Balancing Topics

With the webMethods JMS Provider you can allow multiple JMS clients, each using its 
own session, to process messages from a single topic in parallel, on a first‐come, first‐serve 
basis. 
To allow load balancing of topics across clusters, the following must be true:
To be load balanced, each topic must be configured to share state. This allows 
multiple connections to share the same connection client ID. 
The wmjms.properties file must contain the following system property:
com.webmethods.jms.clientIDsharing=true
The wmjms.properties file must be placed in the Integration Server classpath. 

A durable subscriber must be used to receive messages from the topic. 
For information about creating a JMS topic at the Broker and configuring it to be a shared 
state client, see the webMethods Broker Administrator’s Guide. For more information abut 
creating a wmjms.properties file to contain JMS provider‐specific properties, see the 
webMethods Messaging Programmer’s Guide.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 20

Chapter 2. JMS Basics

JMS Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Messaging Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

JMS API Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 21

 2. JMS Basics

JMS Messaging
The Java Message Service (JMS) is a Java API that allows applications to communicate 
with each other using a common set of interfaces. JMS is part of the Java 2 Platform, 
Enterprise Edition (J2EE) suite. The JMS API provides messaging interfaces, but not the 
implementations.
A JMS provider, such as the webMethods JMS Provider, is a messaging system that 
implements the JMS message interfaces and provides administrative and control features. 
It supports routing and delivery of messages through the implementation of the JMS API 
on the client. A goal of JMS is to maximize the portability of JMS applications across 
different JMS providers.
JMS clients are the programs or components, written in Java, that produce and consume 
messages. 

Messaging Styles
A messaging style refers to how messages are produced and consumed. JMS supports the 
publish‐subscribe (pub‐sub) and point‐to‐point (PTP) messaging styles. 

Point-to-point (PTP) Messaging

In point‐to‐point (PTP) messaging, message producers and consumers are known as 
senders and receivers.
The central concept in PTP messaging is a destination called a queue. A queue represents a 
single receiver. Message senders submit messages to a specific queue and another client 
receives the messages from the queue. 
In the PTP model, a queue may receive messages from many different senders and may 
deliver messages to multiple receivers; however each message is delivered to only one 
receiver.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 22

 2. JMS Basics

Sending Clients

Integration Server
(Sender)
JMS Provider Receiving Client

Integration Server

Integration Server JMS Trigger

(Sender) Queue
(Receiver)

Order Entry Program

(Sender)

Publish-Subscribe Messaging
In publish‐subscribe messaging, message producers and consumers are known as 
publishers and subscribers. 
The central concept in the publish‐subscribe messaging is a destination called a topic. 
Message publishers send messages of specified topics. Clients that want to receive that 
type of message subscribe to the topic.
The publishers and subscribers never communicate with each other directly. Instead, they 
communicate by exchanging messages through a JMS provider 

Publishing Clients Subscribing Clients

Integration Server
Integration Server
(Publisher) JMS Trigger
(Subscriber)
JMS Provider

Integration Server
Integration Server
(Publisher) Topic JMS Trigger
(Subscriber)

Integration Server
Order Entry Program
(Publisher) JMS Trigger
(Subscriber)

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 23

 2. JMS Basics

Publishers and subscribers have a timing dependency. Clients that subscribe to a topic can 
consume only messages published after the client has created a subscription. In addition, 
the subscriber must continue to be active to consume messages.
The messaging APIs relax this dependency by making a distinction between durable 
subscriptions and non‐durable subscriptions.

Durable Subscriptions
Durable subscriptions allow subscribers to receive all the messages published on a topic, 
including those published while the subscriber is inactive. When the subscribing 
applications are not running, the messaging provider holds the messages in nonvolatile 
storage. It retains the messages until either:
The subscribing application becomes active, identifies itself to the provider, and sends 
an acknowledgment of receipt of the message.
The expiration time for the messages is reached. 

Non-durable Subscriptions
Non‐durable subscriptions allow subscribers to receive messages on their chosen topic, only 
if the messages are published while the subscriber is active. You generally use this type of 
subscription for any kind of data that is time sensitive, such as financial information.

JMS API Programming Model

The following section summarizes the most important components of the JMS API. 
The building blocks of a JMS application consist of the following:
Administered objects (connection factories and destinations)

Connections

Sessions

Message producers

Message consumers

Messages

Administered Objects
Administered objects are pre‐configured objects that an administrator creates for use with 
JMS client programs. Administered objects serve as the bridge between the client code 
and the JMS provider. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 24

 2. JMS Basics

By design, the messaging APIs separate the task of configuring administered objects from 
the client code. This architecture maximizes portability: the provider‐specific work is 
delegated to the administrator rather than to the client code. However, the 
implementation must supply its own set of administrative tools to configure the 
administered objects.
JMS administered objects are stored in a standardized namespace called the Java Naming 
and Directory Interface (JNDI). JNDI is a Java API that provides naming and directory 
functionality to Java applications. JNDI provides a way to store and retrieve objects by a 
user supplied name. 

Types of Administered Objects

There are two types of administered objects: connection factories and destinations.

Connection Factories
A connection factory is the object a client uses to create a connection with a JMS provider. It 
encapsulates the set of configuration parameters that a JMS administrator defines for a 
connection.
The type of connection factory determines whether a connection is made to a topic (in a 
publish‐subscribe application), a queue (in a point‐to‐point application), or can be made 
to both (generic connection), and whether messages are managed like elements in a 
distributed transaction in the client application.
You use XA‐based connection factories in JMS applications managed by a J2EE 
application server, in the context of a distributed transaction. 

Destinations
Destinations are the objects that a client uses to specify the target of messages it produces 
and the source of messages it consumes. These objects specify the identity of a destination 
to a JMS API method. There are four types of destinations; only the first two (queues and 
topics) are administered objects:
Queue. A queue object covers a provider‐specific queue name, and is how a client 
specifies the identity of a queue to JMS methods.
Topic. A topic object covers a provider‐specific topic name, and is how a client 
specifies the identity of a topic to JMS methods.
TemporaryQueue. A queue object created for the duration of a particular connection (or 
QueueConnection). It can only be consumed by the connection from which it was 
created.
TemporaryTopic. A topic object that is created for the duration of a particular 
connection (or TopicConnection). It can only be consumed by the connection from 
which it was created.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 25

 2. JMS Basics

Connections
A connection object is an active connection from a client to its JMS provider. In JMS, 
connections support concurrent use. A connection serves the following purposes:
A connection encapsulates an open connection with a JMS provider. It typically 
represents an open TCP/IP socket between a client and the service provider software.
The creation of a connection object is the point where client authentication takes place.

A connection object can specify a unique client identifier.

A connection object supports a user‐supplied ExceptionListener object.
A connection should always be closed once its use is no longer required.

Sessions
A session object is a single‐threaded context for producing and consuming messages. If a 
client uses different threads for different paths of message execution, then a session must 
be created for each of the threads. 
A session is used to create message producers, message consumers, temporary topics, and 
temporary queues; it also supplies provider‐optimized message factories.
In JMS, a session provides the context for grouping a set of send and receive messages into 
a transactional unit.

Message Producer
A message producer is an object that a session creates to send messages to a destination (a 
topic or a queue).

Message Consumer
A message consumer is an object that a session creates to receive messages sent to a 
destination. A message consumer allows a client to register interest in a destination, 
which manages the delivery of messages to the registered consumers of that destination.

Message Selector
A client may want to receive subsets of messages. A message selector allows a client to filter 
the messages it wants to receive by use of a SQL92 string expression in the message 
header. That expression is applied to properties in the message header (not to the message 
body content) containing the value to be filtered.
If the SQL expression evaluates to true, the message is sent to the client; if the SQL 
expression evaluates to false, it does not send the message.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 26

 2. JMS Basics

Messages
Messages are objects that communicate information between client applications. Following 
are descriptions of several key concepts related to JMS messages.

Message Structure
Messages are composed of the following parts:
Header. All messages support the same set of header fields. Header fields contain 
predefined values that allow clients and providers to identify and route messages. 
Each of the fields supports its own set and get methods for managing data; some 
fields are set automatically by the send and publish methods, whereas others must 
be set by the client.
Examples of header fields include:
JMSDestination, which holds a destination object representing the 
destination to which the message is to be sent.
JMSMessageID, which holds a unique message identifier value and is set 
automatically.
JMSCorrelationID, which is used to link a reply message with its requesting 
message. This value is set by the client application.
JMSReplyTo, which is set by the client and takes as a value a Destination object 
representing where the reply is being sent. If no reply is being sent, this field is set 
to null.
See the description of the Message interface in the Java Message Service, Version 1.1 
specification for information about the complete set of message header fields and the 
methods for setting and getting their data.
Properties (optional). Properties are used to add optional fields to the message header. 
There are several types of message property fields. 
Application‐specific properties are typically used to hold message selector values. 
Message selectors are used to filter and route messages. 
Standard properties. The API provides some predefined property names that a 
provider may support. Support for the JMSXGroupID and JMSXGroupSeq is 
required; however, support for all other standard properties is optional.
Provider‐specific properties are unique to the messaging provider and typically refer 
to internal values.
Body (optional). JMS defines various types of message body formats that are compatible 
with most messaging styles. Each form is defined by a message interface:
StreamMessage. A message whose body contains a stream of Java primitive 
values. It is filled and read sequentially.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 27

 2. JMS Basics

MapMessage. A message whose body contains a set of name‐value pairs where 
names are Strings and values are Java primitive types. The entries can be accessed 
sequentially by enumerator or randomly by name. The order of the entries is 
undefined.
TextMessage. A message whose body contains a java.lang.String.

ObjectMessage. A message that contains a Serializable Java object. 

BytesMessage. A message that contains a stream of uninterpreted bytes. This 
message type is for literally encoding a body to match an existing message 
format. In many cases, it will be possible to use one of the other, self‐defining, 
message types instead. 
Both StreamMessage and MapMessage support the same set of primitive data types. 
Conversions from one data type to another are possible.

Message Acknowledgment
A message is not considered to be successfully consumed until it is acknowledged. 
Depending on the session acknowledgment mode, the messaging provider may send a 
message more than once to the same destination. There are several message 
acknowledgment constants:

Value Description

AUTO_ACKNOWLEDGE Automatically acknowledges the successful receipt of a 
message.
CLIENT_ACKNOWLEDGE Acknowledges the receipt of a message when the client 
calls the message’s acknowledge() method.
DUPS_OK_ACKNOWLEDGE Instructs the session to automatically, lazily 
acknowledge the receipt of messages, which reduces 
system overhead but may result in duplicate messages 
being sent.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 28

Chapter 3. Sending and Receiving JMS Messages

The JMS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Sending a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Sending a JMS Message and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Replying to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Receiving a JMS Message Using Built-In Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Sending a JMS Message as Part of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Setting Properties in a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 29

 3. Sending and Receiving JMS Messages

The JMS Services

Using the following JMS services, you can create services that send and/or receive JMS 
messages. The JMS services are located in the WmPublic package. 

Service Description
pub.jms:acknowledge Sends an acknowledgment for a message to the JMS provider.
pub.jms:createConsumer Creates a message consumer to receive messages from 
destinations on the JMS provider.
pub.jms:receive Synchronously receives a message from a queue or topic on 
the JMS provider.
pub.jms:reply Sends a reply message to a requesting client.
pub.jms:send Sends a JMS message to the JMS provider.
pub.jms:sendAndWait Sends a request in the form of a JMS message to the JMS 
provider and optionally, waits for a reply.
pub.jms:waitForReply Retrieves the reply message for an asynchronous request.

Sending a JMS Message

When you build a service that sends a JMS message, you specify how Integration Server 
connects to the JMS provider, the message destination, and whether or not a client side 
queue should be used. 

How to Send a JMS Message

The following describes the general steps you take to send a JMS message to a JMS 
provider.
1 Create an empty flow service.
2 Create the message body.
How you build the message body depends on the format that you want to use for the 
message. For example, if you want to use a String as the message body, create a field 
of type String and then add content to the String field. If you want to use a Document 
(IData) as the message body, create a document and then add content to the 
document. Note that a Document (IData) should only be used when sending a JMS 
message from one Integration Server to another 
If you want more control over the actual javax.jms.Message that Integration Server 
sends to the JMS provider, you can create a Java service that calls the 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 30

 3. Sending and Receiving JMS Messages

com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a 
javax.jms.Message. See:
com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)

com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message, 
which can then be mapped to the JMSMessage/body/message input parameter of the 
pub.jms:send service. 
When creating the javax.jms.Message with the 
com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the 
javax.jms.Message setter methods to set the values of the message headers and 
properties directly. You can also set the value of message headers and properties 
using the input parameters of the pub.jms* service that you use to send the message. If 
you set the message headers and properties both ways, the values provided to the 
pub.jms* service take precedence.
Software AG recommends that you use a pub.jms* service to create and send the JMS 
message. This may provide better performance on average. However, if you want to 
send a StreamMessage or a MapMessage, you need to use the appropriate 
com.wm.app.b2b.server.jms.producer.ProducerFacade API. 
3 Invoke pub.jms:send. This service creates a JMS message (javax.jms.Message) based on 
input provided to the service or takes an existing JMS message and sends it to the JMS 
provider. 
4 Specify the JMS connection alias. The JMS connection alias indicates how Integration 
Server connects to the JMS provider.

Name Description

connectionAliasName Name of the JMS connection alias that you want to use to 
send the message. 

5 Specify the destination to which you want to send the message.

If the JMS connection alias you specified in step 4 uses the native webMethods API to 
create the connection directly on the webMethods JMS Provider, you need to specify 
the destinationName as well as the destinationType

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 31

 3. Sending and Receiving JMS Messages

Name Description

destinationName Name or lookup name of the Destination to which you want to 
send the message. 
Specify the lookup name of the Destination object when 
the JMS connection alias uses JNDI to retrieve 
administered objects. 
Specify the provider‐specific name of the Destination 
when the JMS connection alias uses the native 
webMethods API to connect directly to the webMethods 
JMS Provider.
destinationType Specifies whether the Destination is a queue or a topic. The 
default is queue. 

6 Set values for the header fields in the JMS message. All of the header fields are optional. 

Name Description

deliveryMode Specifies the message delivery mode for the message. Specify 
one of the following:
PERSISTENT provides once‐and‐only‐once delivery for the 
message. The message will not be lost if a JMS provider 
failure occurs.
NON_PERSISTENT provides at‐most‐once delivery for the 
message. The message has no guarantee of being saved if a 
JMS provider failure occurs. 
The default is PERSISTENT
priority Specifies the message priority. JMS defines priority levels from 
0 to 9, with 0 as the lowest priority and 9 as the highest. 
The default is 4.
timeToLive Specifies the length of time, in milliseconds, that the JMS 
provider retains the message. 
The default is 0, meaning that the message does not expire. 
JMSType Message type identifier for the message. 

If you created a javax.jms.Message and you set the message header fields using the 
javax.jms.Message setter methods, you do not need to provide inputs to the fields in 
JMSMessage/header. If you do set message header fields using both approaches, 
Integration Server uses the values provided as input to the pub.jms:send service.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 32

 3. Sending and Receiving JMS Messages

7 Set values for the Integration Server-specific properties. The properties fields are optional 

fields added to the message header and are often used to hold message selector 
values. Integration Server adds the following properties to JMS messages it sends. 
You can set these values as follows.

Name Description

activation Specifies the activation ID for the message. A JMS trigger uses 
the activation ID to join together messages it receives. For 
more information about setting the activation, see “Assigning 
an Activation to a JMS Message” on page 46. 
uuid Specifies a universally unique identifier for a message. For 
more information about setting a UUID, see “Setting the 
UUID” on page 47.

If you created a javax.jms.Message and you set the message property fields using the 
javax.jms.Message setter methods, you do not need to provide inputs to the fields in 
JMSMessage/properties. If you do set message property fields using both approaches, 
Integration Server uses the values provided as input to the pub.jms:send service. 
8 Add any custom properties to the JMS message.

To add a new property to JMSMessage/properties, click   on the Pipeline tab. 
Select a data type for the property and assign it a name. Make sure to place the new 
property in the JMSMessage/properties field. 
Assign a value to any custom properties that you add. 
9 Map data to the body of the JMSMessage document. Specifically, map the field that contains 
the data you want to included in the message body to the field in JMSMessage/body 
with the appropriate data type. 

Map to this field... If you...

string Used a field of type String for the message body content 
bytes Used a one‐dimensional byte array for the message body 
content. 
object Used a Serializable Java object for the message body content.
data Used a Document (IData) for the JMS message body content. 
Keep in mind that the IData message format can only be used 
when sending a JMS message from one Integration Server to 
another. 
message Used a Java service to create an object of type 
javax.jms.Message.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 33

 3. Sending and Receiving JMS Messages

10 Specify client side queueing. When client side queueing is enabled, Integration Server 

places messages in the client side queue if the JMS provider is not available at the time 
the pub.jms:send service executes. 

Name Description

useCSQ Indicates whether Integration Server places the sent message 
in the client side queue if the JMS provider is not available at 
the time the message is sent 
True specifies that Integration Server writes messages to 
the client side queue if the JMS provider is not available at 
the time this service executes. When the JMS provider 
becomes available, Integration Server sends messages 
from the client side queue to the JMS provider.
False indicates that Integration Server throws an 
ISRuntimeException if the JMS provider is not available at 
the time this service executes
The default is True. 

Sending a JMS Message and Waiting for a Reply

Integration Server provides the pub.jms:sendAndWait service, which you can use to send a 
message and wait for a reply.
You can use the pub.jms:sendAndWait service to issue a request/reply in a synchronous or 
asynchronous manner. 
In a synchronous request/reply, the service that sends the request stops executing 
while it waits for a reply. When the service receives a reply message, the service 
resumes execution. If the timeout elapses before the service receives a reply, 
Integration Server ends the request, and the service returns a null message that 
indicates that the request timed out. Integration Server then executes the next step in 
the flow service. 
In an asynchronous request/reply, the service that sends the request continues 
executing the steps in the service after sending the message. To retrieve the reply, the 
requesting flow service must invoke the pub.jms:waitForReply service. If the timeout 
elapses before the pub.jms:waitForReply service receives a reply, the pub.jms:waitForReply 
service returns a null document indicating that the request timed out.   
A service that contains multiple asynchronous send and wait invocations allows the 
service to send all the requests before collecting the replies. This approach can be more 
efficient than sending a request, waiting for a reply, and then sending the next request.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 34

 3. Sending and Receiving JMS Messages

How to Send a Request Message and Wait for a Reply

The following describes the general steps you take to build a service that sends a request 
message and then waits for a reply.
1 Create an empty flow service.
2 Create the message body. For more information about creating content for the body of a 
JMS message, see step 2 in the section “How to Send a JMS Message” on page 30. 
3 Invoke pub.jms:sendAndWait. This service creates a JMS message (javax.jms.Message) 
based on input provided to the service or takes an existing JMS message and sends it 
to the JMS provider. 
4 Specify the JMS connection alias. The JMS connection alias indicates how Integration 
Server connects to the JMS provider.

Name Description

connectionAliasName Name of the JMS connection alias that you want to use to 
send the message. 

5 Specify the destination to which you want to send the message.

If the JMS connection alias you specified in step 4 uses the native webMethods API to 
create the connection directly on the webMethods JMS Provider, you need to specify 
the destinationName as well as the destinationType.

Name Description

destinationName Name or lookup name of the Destination to which you want to 
send the message. 
Specify the lookup name of the Destination object when 
the JMS connection alias uses JNDI to retrieve 
administered objects. 
Specify the provider‐specific name of the Destination 
when the JMS connection alias uses the native 
webMethods API to connect directly to the webMethods 
JMS Provider.
destinationType Specifies whether the Destination is a queue or a topic. The 
default is queue. 

6 Specify the destination to which message recipients should send the reply message. (Optional)
If you do not specify a destination for reply messages, Integration Server uses a 
temporaryQueue to receive the reply. A temporaryQueue is a queue object created for 
the duration of a particular connection. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 35

 3. Sending and Receiving JMS Messages

If the JMS connection alias you specified in step 4 uses the native webMethods API to 
create the connection directly on the webMethods JMS Provider, you need to specify 
the destinationNameReplyTo as well as the destinationTypeReplyTo.

Name Description

destinationNameReplyTo Name or lookup name of the Destination to which you 
want the reply message sent.
Specify the lookup name of the Destination object 
when the JMS connection alias uses JNDI to retrieve 
administered objects. 
Specify the provider‐specific name of the 
Destination when the JMS connection alias uses the 
native webMethods API to connect directly to the 
webMethods JMS Provider.
destinationTypeReplyTo Specifies whether the Destination is a queue or a topic. 
The default is queue. 

7 Set the request timeout. The timeout indicates how long Integration Server waits for a 

reply message. The timeout parameter only applies to synchronous send and wait 
requests. 

Name Description

timeout Time to wait (in milliseconds) for the response to arrive. If 
no value is specified, the service does not wait at all. 

8 Populate the JMS message. To populate the JMS message header, properties, and body, 

follow steps 5–9 in the section “How to Send a JMS Message” on page 30.
9 Determine whether the request is synchronous or asynchronous. The pub.jms:sendAndWait 
provides a parameter that you can set to indicate whether the request is synchronous 
or asynchronous. By default, the request is synchronous. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 36

 3. Sending and Receiving JMS Messages

Name Description

async Flag specifying whether this is an asynchronous or 
synchronous request/reply. 
True indicates that this is an asynchronous 
request/reply. After sending the message, 
Integration Server executes the next step in the flow 
service immediately. The Integration Server does 
not wait for a reply before continuing service 
execution.
False indicates that this is a synchronous 
request/reply. After sending the message, 
Integration Server waits for a reply before executing 
the next step in the flow service. 
The default is False.

10 Specify client side queueing. When client side queueing is enabled, Integration Server 

places messages in the client side queue if the JMS provider is not available at the time 
the pub.jms:send service executes. 
Client side queueing can be used with asynchronous requests only. 

Name Description

useCSQ Indicates whether Integration Server places the sent message 
in the client side queue if the JMS provider is not available at 
the time the message is sent 
True specifies that Integration Server writes messages to 
the client side queue if the JMS provider is not available at 
the time this service executes. When the JMS provider 
becomes available, Integration Server sends messages 
from the client side queue to the JMS provider.
False indicates that Integration Server throws an 
ISRuntimeException if the JMS provider is not available at 
the time this service executes
The default is True. 

11 Invoke pub.jms:waitForReply. If you configured pub.jms:sendAndWait as an asynchronous 
request/reply, you need to invoke the pub.jms:waitForReply service to retrieve the reply 
message. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 37

 3. Sending and Receiving JMS Messages

Specify the following input values for the pub.jms:waitForReply service.

Name Description

correlationID A unique identifier used to associate the reply message with 
the initial request. Integration Server uses the value of the uuid 
or JMSMessageID fields in the requesting JMS message to 
correlate the response to the request
If you set the uuid in the JMS message request, you can 
link the value of the uuid field from the JMSMessage 
produced by pub.jms:sendAndWait to the correlationID.
If you did not specify a uuid, you can link the 
JMSMessageID field from the JMSMessage produced by 
pub.jms:sendAndWait to the correlationID.
timeout Optional. Time to wait (in milliseconds) for the reply to arrive. 
If no value is specified, the service does not wait for a reply. 

12 Process the reply message. The pub.jms:sendAndWait (or pub.jms:waitForReply) service 

produces the output parameter JMSReplyMessage, which contains the JMS message 
received as a reply. 
If Integration Server does not receive a reply before the specified timeout value 
elapses, the JMSReplyMessage is null. Be sure to code your service to handle this 
situation. 

Replying to a JMS Message

You can create a service that sends a reply message in response to a received request 
message. The reply message might be a simple acknowledgement or might contain 
information requested by the sender. 
When you send a reply message, Integration Server uses information in the request 
message to determine the reply destination. The JMSReplyTo field in the request message 
is set by the sending client and indicates the destination to which the reply will be sent. 
The replying Integration Server automatically sets this value when it executes the 
pub.jms:reply service. 
When replying to a message, Integration Server also automatically sets the 
JMSCorrelationID in the reply message. Integration Server, and many JMS clients, use the 
JMSCorrelationID to correlate the reply message with the request message. Integration 
Server uses the value of either the uuid or JMSMessageID fields in the requesting JMS 
message to correlate the request and the response. 
If the sender of the request message specified the uuid, the replying Integration Server 
will use the uuid as the JMSCorrelationID of the reply message. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 38

 3. Sending and Receiving JMS Messages

If the sender of the request message did not specify a uuid, the replying Integration 
Server uses the JMSMessageID from the request message as the JMSCorrelationID of 
the reply message. 

How to Send a Reply Message

The following describes the general steps you take to build a service that sends a reply 
message. 
1 Open or create the service that will send the reply. If a JMS trigger received the message, 
this might be the trigger service or a service invoked by the trigger service. If you used 
the pub.jms:receive service to retrieve the message from the JMS provider, you might 
reply to the message within the same service or in another service invoked by the 
same top‐level service. 
2 Invoke pub.jms:reply. This service takes the reply message you created and delivers it to 
the destination specified in the JMSReplyTo field in the header of the request message. 
3 Populate the JMS message. If a JMS trigger received the message, populate the JMS 
message header, properties, and body, follow steps 5–9 in the section “How to Send a 
JMS Message” on page 30.
4 Specify the consumer and message. If you received the message using the pub.jms:receive 
service, you must specify the message consumer used to receive the message and the 
request message. You do not need to specify this information if a JMS trigger received 
the message.

Name Description

consumer The message consumer object used to receive the request 
message from the JMS provider. Integration Server uses 
information from the consumer to create a message producer 
that will send the reply message. 
message A javax.jms.Message object that contains the request message. 
You can map the JMSMessage/body/message field in the request 
message to the pub.jms:reply message input parameter. The 
pub.jms:reply service uses the request message to determine the 
replyTo destination.

Receiving a JMS Message Using Built-In Services

At times, you might not want to wait for a JMS trigger to execute to receive a message. 
Instead, you might want to receive a message from the JMS provider on demand. 
Receiving a message on demand provides more control over when and how Integration 
Server receives a message; however, it may not be as efficient or practical as using a JMS 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 39

 3. Sending and Receiving JMS Messages

trigger to listen for and then receive the message. You can use the pub.jms:receive service 
to retrieve messages on demand from the JMS provider. 
To listen for messages and receive them when they are available, create a JMS trigger that 
listens to the destination. For more information about creating a JMS trigger, see 
Chapter 4, “Working with JMS Triggers”

How to Actively Receive a JMS Message

The following describes the general steps you take to build a service that receives a 
message from the JMS provider. 
1 Create a new service.
2 Invoke pub.jms:createConsumer. This service creates a message consumer that receives 
messages sent to a particular destination. 
Use the following steps to create the message consumer.
a Specify the JMS connection alias. The JMS connection alias indicates how Integration 
Server connects to the JMS provider.

Name Description

connectionAliasName Name of the JMS connection alias that you want to use 
to receive the message. 

b Specify the destination from which you want to receive the message. Specify the 
messages that you want the consumer to receive by selecting a destination and by 
creating a message selector. A message selector is an filter that is evaluated by the 
JMS provider. If a message does not meet the criteria specified in the filter, the 
consumer does not receive the message. Use a message selector receive a subset of 
messages from a destination.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 40

 3. Sending and Receiving JMS Messages

Name Description

destinationName Name or lookup name of the Destination from which 
you want to receive the message. 
Specify the lookup name of the Destination object 
when the JMS connection alias uses JNDI to 
retrieve administered objects. 
Specify the provider‐specific name of the 
Destination when the JMS connection alias uses 
the native webMethods API to connect directly to 
the webMethods JMS Provider.
destinationType Specifies whether the Destination is a queue or a topic. 
The default is queue. 
If the JMS connection alias you specified in step 2a 
uses the native webMethods API to create the 
connection directly on the webMethods JMS Provider, 
you need to specify the destinationName as well as the 
destinationType.
messageSelector Optional Specifies a filter used to receive a subset of 
messages from the specified destination. 
The message selector must use the message selector 
syntax specified in the Java Message Service 
Specification Version 1.1 
For more information about message selectors, see 
“Creating a Message Selector” on page 56.
durableSubscriberName Optional. Name of the durable subscriber that you 
want this service to create/use on the JMS provider. A 
durable subscriber creates a durable subscription on 
the JMS provider. If a durable subscriber of this name 
already exists on the JMS provider, this service 
resumes the previously established subscription. 

Note: This parameter only applies when the 
destinationType is set to TOPIC. If you select TOPIC, but 
do not specify a durableSubscriberName, this service 
creates a nondurable subscriber. If destinationType is set 
to QUEUE, this parameter is ignored. 

c Determine the acknowledgment mode. Acknowledgment mode indicates how Integration 

Server acknowledges messages received by a message consumer.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 41

 3. Sending and Receiving JMS Messages

Use the following parameter to specify the acknowledgment mode.

Name Description

acknowledgmentMode AUTO_ACKNOWLEDGE Automatically acknowledge 

the message when it is received by the message 
consumer. The message consumer will 
acknowledge the message before the message 
processing completes. The JMS provider cannot 
redeliver the message if Integration Server 
becomes unavailable before message processing 
completes.
CLIENT_ACKNOWLEDGE Acknowledge the receipt of 
a message when the JMS client (Integration Server) 
invokes pub.jms:acknowledge service. 
DUPS_OK_ACKNOWLEDGE Automatically, lazily 
acknowledge the receipt of messages, which 
reduces system overhead but may result in 
duplicate messages being sent.
The default is AUTO_ACKNOWLEDGE.

d Indicate whether locally published messages are ignored. If you specified TOPIC as the 

destinationType, you can configure a consumer to ignore messages published using 
the same JMS connection alias used by the consumer.
Integration Server considers a message to be local if it is:
Sent by the same Integration Server, and 
Sent using the same JMS connection alias. 

Name Description

noLocal Indicates whether the consumer ignores locally 
published messages:
True indicates the consumer will not receive 
locally published messages.
False indicates the consumer can receive locally 
published messages
The default is False. 

3 Invoke pub.jms:receive. This service uses the consumer created by the 

pub.jms:createConsumer service to receive messages from the specified destination. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 42

 3. Sending and Receiving JMS Messages

In the Pipeline tab, make sure the consumer created by the pub.jms:createConsumer 
service is linked to the pub.jms:receive service input parameter consumer. Developer 
should link these automatically. 
Specify how long the consumer should wait to receive a message from the JMS 
provider. 

Name Description

timeout Specifies the time to wait, in milliseconds, for a message to be 
received from the JMS provider. 
If you specify 0 (zero), the consumer will not wait.
The default is 0 (zero). 

4 Process the received JMS message. Invoke a service or a sequence of services to process 

the message received from the JMS provider. In the Pipeline tab, link the JMSMessage 
returned by pub.jms:receive to the input for the service that processes the message.
If the timeout period elapses before a message is received, the value of JMSMessage is 
null. Make sure to code your service to handle this situation. 
5 Invoke pub.jms:acknowledge. If the acknowledgment mode of the consumer that received 
the message is set to CLIENT_ACKNOWLEDGE use the pub.jms:acknowledge service to 
acknowledge the message to the JMS provider. A message is not considered to be 
successfully consumed until it is acknowledged.
Provide the following input parameter.

Name Description

message A javax.jms.Message object that identifies the message for 
which you want Integration Server to send an 
acknowledgement to the JMS provider. 
You can map the value of the JMSMessage/body/message field in 
the JMS message retrieved by the pub.jms:receive service to this 
field.

If you use the consumer created by the pub.jms:createConsumer service to receive multiple 
messages, keep in mind that acknowledging a message automatically acknowledges 
the receipt of all messages received in the same session. That is, all messages received 
by the same consumer will be acknowledged when just one of the received messages is 
acknowledged. Therefore, if the consumer receives multiple messages, invoke the 
pub.jms:acknowledge service after processing all of the received messages. 
Any message consumers created during the execution of a service will be closed 
automatically when the service completes. If the consumer closes without 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 43

 3. Sending and Receiving JMS Messages

acknowledging messages, messages are implicitly recovered back to the JMS 
provider. 

Sending a JMS Message as Part of a Transaction

 

A transaction is a logical unit of work, composed of many different processes and 
involving one or more resources, that either entirely succeeds or has no effect at all. 
Transactions can either be implicit or explicit. 
In an implicit transaction, the transaction manager in Integration Server automatically 
manages the transactions without requiring any additional services or input. In an explicit 
transaction, you control the transactional units of work by defining the start and 
completion boundaries of the transaction. The WmART package on Integration Server 
provides built‐in services that you can use to start and complete transactions.
In some situations, you might use the built‐in service pub.art.transaction:startTransaction to start 
a transaction explicitly, but then allow Integration Server to commit or roll back the 
transaction implicitly based on the success or failure of the service. 
For more information about transactions, see Appendix C, “Transaction Management”. 
You can create a service that sends or receives JMS messages within an explicit 
transaction. The service must do the following:
Use pub.art.transaction:startTransaction to start the transaction.

Create a connection to the JMS provider using a JMS connection alias with a 
transaction type of LOCAL_TRANSACTION or XA_TRANSACTION, depending on 
the kind of transaction.
Use pub.art.transaction:commitTransaction to commit the transaction.

Use pub.art.transaction:rollbackTransaction to roll back the transaction.
Keep the following points in mind when building services that send or receive JMS 
messages within a transaction:
To send or receive JMS messages within a transaction, you must install and enable the 
WmART package. (This is true even if you intend to use Integration Server to manage 
all transactions implicitly.)
To use pub.jms:send or pub.jms:sendAndWait within a transaction, client side queuing 
cannot be used (the useCSQ parameter must be set to false).
To use pub.jms:sendAndWait within a transaction, the request/reply must be 
asynchronous (the async parameter must be set to true). If async is set to false, 
Integration Server throws a JMSSubsystemException when the service executes.
If you do not specifically invoke pub.art.transaction:commitTransaction or 
pub.art.transaction:rollbakTransaction, Integration Server implicitly commits the transaction 
when the services within the transaction are successful. Integration Server implicitly 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 44

 3. Sending and Receiving JMS Messages

rolls back the transaction when one of the services within the transaction fails with 
any type of exception. 

How to Send a JMS Message within a Transaction

The following describes the general steps you take to send a JMS message to a JMS 
provider as part of a transaction (XA or Local). 
1 Create an empty flow service.
2 Create the message body. For more information about creating content for the body of a 
JMS message, see step 2 in the section “How to Send a JMS Message” on page 30. 
3 Invoke pub.art.transaction:startTransaction. This service starts an explicit transaction. This 
service is located in the WmART package. 
In the startTransactionInput document list, you can provide the following optional 
parameter:

Name Description

transactionName A String that specifies the name of the transaction to be 
started. If this field is blank Integration Server will generate a 
name for you. 

If you do not use pub.art.transaction:startTransaction to start an explicit transaction, 
Integration Server starts an implicit transaction when it executes a pub.jms:send service 
that speechifies a transacted JMS connection alias. 
4 Invoke pub.jms:send. This service takes the JMS message you created and sends it to the 
JMS provider. 
5 Specify the JMS connection alias. The JMS connection alias indicates how Integration 
Server connects to the JMS provider.

Name Description

connectionAliasName Name of the JMS connection alias that you want to use to 
send the message. 
The specified JMS connection alias must have a transaction 
type of LOCAL_TRANSACTION or 
XA_TRANSACTION, depending on the kind of 
transaction.

6 Finish supplying inputs to the pub.jms:send service. Follow steps 5‐9 under “How to Send a 

JMS Message” on page 30.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 45

 3. Sending and Receiving JMS Messages

7 Add any additional services to the transaction. For example, you might want to invoke 

another built‐in JMS service or an adapter service. 
8 Insert logic to commit and/or rollback the transaction explicitly. You may build your service 
to commit the transaction if all services execute successfully and to rollback the 
transaction if all services do not execute successfully.
Invoke pub.art.transaction:commitTransaction to commit the transaction and send the 
JMS message. On the Pipeline tab, map the contents of 
startTransactionOutput/transactionName to commitTransactionInput/transactionName. 
Invoke pub.art.transaction:rollbakTransaction to roll back the transaction. The message 
will not be sent to the JMS provider. On the Pipeline tab, map the contents of 
startTransactionOutput/transactionName to rollbackTransactionInput/transactionName. 
If you do not specifically invoke pub.art.transaction:commitTransaction or 
pub.art.transaction:rollbakTransaction, Integration Server implicitly commits the transaction 
when the services within the transaction are successful. Integration Server implicitly 
rolls back the transaction when one of the services within the transaction fails with 
any type of exception.

Setting Properties in a JMS Message

Properties are an optional part of a JMS message that enable you to add fields to the 
message header. Properties usually hold message selector values and are application‐
specific, standard, or provider‐specific. 
When building a service that sends a JMS message, you can:
Add your own custom properties to the JMSMessage/properties document using the 
pipeline in Developer. 
Assign values to the application‐specific properties activation and uuid included by 
Integration Server.
The following sections provide information about setting the activation and uuid. For 
information about adding fields to the pipeline in Developer, see the webMethods Developer 
User’s Guide.

Assigning an Activation to a JMS Message

An activation is a unique identifier assigned to a message that will be processed by a JMS 
trigger that contains a join. A join specifies that a JMS trigger handles messages received 
from two or more destinations as a single unit and with a single routing rule. The JMS 
trigger needs to receive messages from all, only one, or any of the destinations before it 
executes the associated routing rule. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 46

 3. Sending and Receiving JMS Messages

Because a JMS trigger can receive multiple messages from the destinations, Integration 
Server uses the activation value to identify the set of messages processed by an instance of 
a join. 
For an All (AND) join, Integration Server waits until it receives messages with the 
same activation from each destination before executing the routing rule. 
For an Only one (XOR) join, Integration Server executes the routing rule after it 
receives a message from any destination in the join; however, the JMS trigger discards 
messages with the same activation received from the other destinations for the 
duration of the join time‐out. 
For an Any (OR) join, Integration Server executes the routing rule when it receives 
messages from any destination in the join. Integration Server does not use the 
activation value when processing JMS triggers with an Any (OR) join. 
When the JMS trigger receives messages with a different activation from one the 
destinations, Integration Server treats it as another instance of the join. 
Integration Server stores the activation in the activation field of a JMS message, specifically, 
JMSMessage/properties/activation. The activation field is of type String.You assign an 
activation to a message manually. Integration Server does not assign an activation 
automatically. 

Setting the UUID

The UUID is a universally unique identifier for a message. Integration Server uses the 
UUID to provide duplicate detection for exactly‐once processing. Integration Server stores 
the UUID in the JMSMessage/properties/uuid field. 
You might want to assign a UUID in the following situations: 
The JMS message originated in a back‐end system that assigned a unique identifier to 
the message data. You can map the value assigned by the system to the 
JMSMessage/properties/uuid field. A JMS trigger that receives the message can use the 
assigned UUID to filter out duplicate messages from a back‐end system. 
 A JMS message is part of a request/reply. If you specify the uuid when sending the 
request, the replying Integration Server will use the uuid as the JMSCorrelationID of 
the reply message. If you do not specify a uuid, the replying Integration Server uses 
the JMSMessageID of the request message as the JMSCorrelationID of the reply 
message. 
The maximum length of a UUID is 96 characters. Integration Server does not assign a 
UUID automatically.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 47

 3. Sending and Receiving JMS Messages

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 48

Chapter 4. Working with JMS Triggers

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Overview of Building a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

JMS Trigger Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Creating a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Enabling or Disabling a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Setting an Acknowledgment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Setting a Join Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Specifying the Execution User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Specifying Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Handling Fatal Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Handling Transient Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Generating Events for JMS Retrieval Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Debugging a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Building JMS Triggers with Multiple Routing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 49

 4. Working with JMS Triggers

Introduction
A JMS trigger specifies the destinations (queues or topics) on a JMS provider from which 
the JMS trigger would like to receive messages. The JMS trigger also contains routing 
rules, which specify the service that Integration Server invokes to process a message 
received by the JMS trigger. 

Overview of Building a JMS Trigger

Building a JMS trigger is a process that involves the following basic stages.

Stage Description

1 Create a new JMS trigger on Integration Server. During this stage, you use 

Developer to create the new JMS trigger on the Integration Server where 
you will do your development and testing. For more information, see 
“Creating a JMS Trigger” on page 51.

2 Specify a JMS connection alias. During this stage, you specify the JMS 

connection alias that Integration Server uses to create connections to the 
JMS provider. The transaction type of the JMS connection alias determines 
whether or not the JMS trigger receives and processes messages as part of 
transaction. 

3 Specify JMS destinations and message selectors. During this stage, you specify 

the destinations (queues or topics) on the JMS provider to which the JMS 
trigger subscribes. That is, the destination is the source of the messages 
that the JMS trigger consumes. You also specify any message selectors that 
you want the JMS provider to use to filter the messages it enqueues for the 
JMS trigger. 

4 Create routing rules. During this stage, you specify the service that 

Integration Server invokes when the JMS trigger receives messages. You 
can also specify a local filter that Integration Server applies to messages.

5 Set JMS trigger properties. During this stage, you determine the type of 

message processing, the acknowledgement mode, fatal and transient error 
handling, and exactly‐once processing.

6 Test and debug the JMS trigger. During this stage, you test and debug the 

trigger using the tools provided by Integration Server. For more 
information, see “Debugging a JMS Trigger” on page 73.

JMS Trigger Service Requirements

The service that processes a message received by a JMS trigger is called a trigger service. 
Each routing rule in a JMS trigger specifies a single trigger service.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 50

 4. Working with JMS Triggers

Before a JMS trigger can be enabled, the trigger service must already exist on the same 
Integration Server. Additionally, the signature for the trigger service must reference one of 
the following specifications:
Use pub.jms:triggerSpec as the specification reference if the trigger service will process 
one message at a time. 
Use pub.jms:batchTriggerSpec as the specification reference if the trigger service will 
process multiple messages at one time. That is, the trigger service will receive a batch 
of messages as input and process all of those messages in a single execution. A trigger 
that receives and processes a batch of messages is sometimes referred to as a batch 
trigger. 
For more information about batch triggers, see “Processing Messages in Batches” on 
page 63.

Creating a JMS Trigger

When you create a JMS trigger, keep the following points in mind:
The JMS connection alias you want Integration Server to use to obtain connections to 
and receive messages from the JMS provider must already exist. Although a JMS 
connection alias does not need to be enabled at the time you create the JMS trigger, the 
JMS connection alias must be enabled for the JMS trigger to execute at run time. 
If you use a JNDI provider to store JMS administered objects, the Connection 
Factories and Destinations (queues and topics) that you want this JMS trigger to use to 
consume messages must already exist. 
If you use the native webMethods API to connect directly to the webMethods JMS 
Provider, the Destinations from which you want the JMS trigger to receive messages 
must exist on the Broker. For more information about creating Destinations on the 
Broker, see the webMethods Broker Administrator’s Guide.
The transaction type of the JMS connection alias determines whether or not the JMS 
trigger is transacted (that is, it receives and processes messages as part of a 
transaction). Transacted JMS triggers have slightly different properties and operate 
differently than non‐transacted JMS triggers. For more information about building a 
transacted JMS trigger, see Chapter 5, “Building a Transacted JMS Trigger”.
The trigger service that you want to specify in the routing rule must already exist on 
the same Integration Server on which you create the JMS trigger. For more 
information about trigger service requirements, see “JMS Trigger Service 
Requirements” on page 50.
A JMS trigger can contain multiple routing rules. Each routing rule must have a 
unique name. For more information about using multiple routing rules, see “Building 
JMS Triggers with Multiple Routing Rules” on page 74.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 51

 4. Working with JMS Triggers

A JMS trigger that contains an All (AND) or Only one (XOR) join can only have one 
routing rule and cannot have a batch processing size (Max batch messages property) 
greater than 1. A JMS trigger with an Any (Or) join can have multiple routing rules. 
For more information about batch processing, see “Processing Messages in Batches” 
on page 63. 
To use All (AND) or Only one (XOR) joins, the ISInternal alias needs to point to an 
external database. For more information about setting up an external database, see the 
webMethods Installation Guide.

To create a JMS trigger

1 On the File menu, click New.
2 In the New dialog box, select Trigger, and click Next.
3 In the New Trigger dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the trigger.
b In the Name field, type a name for the trigger using any combination of letters, 
and/or the underscore character. For a list of reserved words and symbols or 
element names, see the webMethods Developer User’s Guide.
c Click Next.
d In the newTriggerName dialog box, select JMS Trigger and click Finish.
Developer generates the new trigger and displays it in the Developer window.

4 In the JMS trigger editor, in the JMS Connection Alias Name field, click  . 

5 In the Select a JMS connection alias for triggerName dialog box, select the JMS 
connection alias that you want this JMS trigger to use to receive messages from the 
JMS provider. Click OK. Developer sets the Transaction type property to match the 
transaction type specified for the JMS connection alias.
If a JMS connection alias has not yet been configured on Integration Server, Developer 
displays a message stating the JMS subsystem has not been configured. For 
information abut creating a JMS connection alias, see “Working with JMS Connection 
Aliases” on page 13. 

6 Under JMS destinations and message selectors, click  .
7 Use the following steps to specify the destinations from which the JMS trigger will 
receive messages: 
a In the Destination Name column, type the name or lookup name of the Destination 
from which you want the JMS trigger to receive messages. 
Specify the lookup name of the Destination object when the JMS connection alias 
uses JNDI to retrieve administered objects. Specify the provider‐specific name of 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 52

 4. Working with JMS Triggers

the Destination when the JMS connection alias uses the native webMethods API 
to connect directly to the webMethods JMS Provider. 
b In the Destination Type column, select the type of destination:

Select... If...

Queue The destination is a queue. 
This is the default.
Topic The destination is a topic. 

c In the JMS Message Selector column, click  . In the JMS Message Selector dialog 

box, enter the expression that you want to use to receive a subset of messages 
from this destination and click OK. 
A message selector is a filter evaluated by the JMS provider. If a message does not 
meet the criteria specified in the message selector, the JMS trigger does not receive 
the message. For more information about creating a JMS message selector, see 
“Creating a Message Selector” on page 56.
d If you specified a destination type of topic and you want to create a durable 
subscriber, in the Durable Subscriber Name column, enter a name for the subscriber. 
The name must be unique for that topic. 
A durable subscriber creates a durable subscription on the JMS provider. A 
durable subscription allows subscribers to receive all the messages published on a 
topic, including those published while the subscriber is inactive.
e If you specified a destination type of topic and you want the JMS trigger to ignore 
messages sent using the same JMS connection alias as the JMS trigger, select the 
check box in the Ignore Locally Published column.
8 Repeat step 7 for each destination from which you want the JMS trigger to receive 
messages.
9 If you selected multiple destinations, select the join type. The join type determines 
whether Integration Server needs to receive messages from all, any, or only one of 
destinations to execute the trigger service. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 53

 4. Working with JMS Triggers

Select... If you want...

All (AND) Integration Server to invoke the trigger service when the 

trigger receives a message from every destination within the 
join time‐out period. The messages must have the same 
activation ID. 
For more information about activation IDs, see “Setting 
Properties in a JMS Message” on page 46.
Any (OR) Integration Server to invoke the trigger service when the 
trigger receives a message from any of the specified 
destinations. 
This is the default join type. 

Note: Using an Any (OR) join is similar to creating multiple 
JMS triggers that listen to different destinations. While a JMS 
trigger with an Any (OR) join will use fewer resources (a 
single thread will poll each destination for messages), it may 
cause a decrease in performance (it may take longer for one 
thread to poll multiple destinations). 

Only one (XOR) Integration Server to invoke the trigger service when it 

receives a message from any of the specified destinations. For 
the duration of the join time‐out period, the Integration Server 
discards any messages with the same activation ID that the 
trigger receives from the specified destinations. 
For more information about activation IDs, see “Setting 
Properties in a JMS Message” on page 46.

10 Under Message routing, click   to add a new routing rule. 
11 Create a routing rule by providing the following information: 
a In the Name column, type a name for the routing rule. By default Developer 
assigns the first rule the name “Rule 1”.

b In the Service column, click   to navigate to and select the service that you want 
to invoke when Integration Server receives messages from the specified 
destinations.

c In the Local Filter column, click   to enter the filter that you want Integration 

Server to apply to messages this JMS trigger receives.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 54

 4. Working with JMS Triggers

Integration Server evaluates a local filter after it receives the message from the 
JMS provider. For more information about creating a local filter, see “Creating a 
Local Filter” on page 56. 
12 In the Properties panel, set properties for the JMS trigger. 

Property group or name... Refer to...

Enabled “Enabling or Disabling a JMS Trigger” on page 57
Acknowledgement mode “Setting an Acknowledgment Mode” on page 58
Join expires and Expire “Setting a Join Timeout” on page 59
after
Execution user “Specifying the Execution User” on page 61
Message processing “Specifying Message Processing” on page 62
Fatal error handling “Handling Fatal Errors for Non‐Transacted JMS 
Triggers” on page 65
Transient error handling “Handling Transient Errors for Non‐Transacted JMS 
Triggers” on page 66
Exactly once Chapter 6, “Exactly‐Once Processing for JMS Triggers”
Permissions webMethods Developer User’s Guide

13 On the File menu, click Save.
Notes:
When you select “Topic” as the destination type and specify a durable subscriber 
name, Integration Server creates a a durable subscriber for the JMS trigger on the JMS 
provider. A durable subscriber establishes a durable subscription with a unique identity 
on the JMS provider. A durable subscription allows subscribers to receive all the 
messages published on a topic, including those published while the subscriber is 
inactive (for example, if the JMS trigger is disabled). When the associated JMS trigger 
is disabled, the JMS provider holds the messages in nonvolatile storage. If a durable 
subscription already exists for the specified durable subscriber on the JMS provider, 
this service resumes the subscription. 
When you select “Topic” as the destination type, but do not specify a durable 
subscriber name, Integration Server creates a non‐durable subscriber for the JMS 
trigger. 
A non‐durable subscription allows subscribers to receive messages on their chosen 
topic only if the messages are published while the subscriber is inactive. A non‐
durable subscription lasts the lifetime of its message consumer.
Integration Server uses a consumer to receive messages for a JMS trigger. This 
consumer encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 55

 4. Working with JMS Triggers

Creating a Message Selector

If you want the JMS trigger to receive a subset of messages from a specified destination, 
create a message selector. A message selector is an expression that specifies the criteria for 
the messages in which the JMS trigger is interested.
The JMS provider applies the message selector to messages it receives. If the selector 
evaluates to true, the message is sent to the JMS trigger. If the selector evaluates to false, 
the message is not sent to the JMS trigger.
By creating message selectors, you can delegate some filtering work to the JMS provider. 
This can preserve Integration Server resources that otherwise would have been spent 
receiving and processing unwanted messages. 
The message selector must use the message selector syntax specified in the Java Message 
Service, Version 1.1. The message selector can reference header and property fields in the 
JMS message only. 

Note: If you want to filter on the contents of the JMS message body, write a local filter. 
Integration Server evaluates a local filter after the JMS trigger receives the message from 
the JMS provider. For more information about creating a local filter, see “Creating a Local 
Filter” below.

Creating a Local Filter

You can further refine a JMS trigger by creating local filters. A local filter specifies criteria 
for the contents of the message body. Integration Server applies a local filter to a message 
after the JMS trigger receives the message from the JMS provider. If the message meets the 
filter criteria, Integration Server executes the trigger service specified in the routing rule. If 
the message does not meet the filter criteria, Integration Server discards the message and 
acknowledges the message to the JMS provider. 
If a JMS trigger contains multiple routing rules to support ordered service execution, you 
can use local filters to process a series of messages in a particular order. For more 
information about ordered service execution, see “Building JMS Triggers with Multiple 
Routing Rules” on page 74.
To create a local filter, use the syntax specified in the “Conditional Expressions” appendix 
in the webMethods Developer User’s Guide.
When creating a local filter, you can exclude the JMSMessage document from the filter 
even though it is part of the pipeline provided to the JMS trigger service. For example, a 
filter that matches those messages where the value of the myField field is “XYZ” would 
look like the following:
%properties/myField% == “XYZ”

Note that even though the properties field is a child of the JMSMessage document, the 
JMSMessage document does not need to appear in the filter expression.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 56

 4. Working with JMS Triggers

The following filter matches those messages where the data document within the 
JMSMessage body document contains a field named myField whose value is “A”:
%body/data/myField% == “A”

Note: When receiving a batch of messages, Integration Server evaluates the local filter 
against the first message in the batch only. For more information about batch processing, 
see “Processing Messages in Batches” on page 63.

Enabling or Disabling a JMS Trigger

In Developer, you can enable or disable a JMS trigger. A JMS trigger can have one of the 
following states:

Trigger State Description

Enabled The JMS trigger is running and connected to the JMS provider. 
Integration Server retrieves and processes messages for the JMS 
trigger. 
Disabled The JMS trigger is stopped. Integration Server neither retrieves nor 
processes messages for the JMS trigger.
Suspended The JMS trigger is running and connected to the JMS provider. 
Integration Server has stopped message retrieval, but continues 
processing any messages it has already retrieved.

Note: You can suspend a JMS trigger using Integration Server 
Administrator or the pub.triggers:suspendJMSTriggers service. 

To enable or disable a JMS trigger

1 In the Navigation panel, open the JMS trigger that you want to enable or disable.
2 In the Properties panel, under General, set the Enabled property to one of the following:

Select... To...

True Enable a JMS trigger that is currently disabled.
False Disable a JMS trigger that is currently enabled. 

3  On the File menu, click Save. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 57

 4. Working with JMS Triggers

Notes:
When you disable a JMS trigger, Integration Server interrupts any server threads that 
are processing messages. If the JMS trigger is currently processing messages, 
Integration Server waits 3 seconds before forcing the JMS trigger to stop processing 
messages. If it does not complete within 3 seconds, Integration Server stops the 
message consumer used to receive messages for the JMS trigger and closes the JMS 
consumer. At this point the server thread for the JMS trigger may continue to run to 
completion. However, the JMS trigger will not be able to acknowledge the message 
when processing completes. If the message is persistent, this can lead to duplicate 
messages.
You can disable one or more JMS triggers using the pub.triggers:disableJMSTriggers
service. 
You can enable one or more JMS triggers using the pub.triggers:enableJMSTriggers service. 

You can enable, disable, and suspend one or more JMS triggers using Integration 
Server Administrator. For more information, see “Enabling, Disabling, and 
Suspending JMS Triggers” on page 106.

Setting an Acknowledgment Mode

Acknowledgment mode indicates how Integration Server acknowledges messages received 
on behalf of a JMS trigger. A message is not considered to be successfully consumed until 
it is acknowledged. 

Note: The Acknowledgement mode property is not available for transacted JMS triggers. That 

is, if the JMS connection alias is of type XA_TRANSACTION or 
LOCAL_TRANSACATION, Developer does not display the Acknowledgement mode 
property.

To set an acknowledgment mode

1 In the Navigation panel, open the JMS trigger for which you want to set the 
acknowledgment mode.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 58

 4. Working with JMS Triggers

2 In the Properties panel, under General, select one of the following for Acknowledgment
mode:

Select... To...

AUTO_ACKNOWLEDGE Automatically acknowledge the message when 
it is received by the JMS trigger. Integration 
Server will acknowledge the message before the 
trigger completes processing. The JMS provider 
cannot redeliver the message if Integration 
Server becomes unavailable before message 
processing completes. 
CLIENT_ACKNOWLEDGE Acknowledge or recover the message only after 
the JMS trigger processes the message 
completely.
This is the default. 
DUPS_OK_ACKNOWLEDGE Lazily acknowledge the delivery of messages. 
This may result in the delivery of duplicate 
messages. 

3 On the File menu, click Save. 

Setting a Join Timeout

When you create a join (a JMS trigger that receives messages from two or more 
destinations), you need to specify a join time‐out. A join time‐out specifies how long 
Integration Server waits for additional messages to fulfill the join. Integration Server starts 
the join time‐out period when it receives the first message that satisfies the join. 

Note: You need to specify a join time‐out only when the join type is All (AND) or Only one

(XOR). You do not need to specify a join time‐out for an Any (OR) join. 

The implications of a join time‐out are different depending on the join type. 

Join Time-outs for All (AND) Joins

A join time‐out for an All (AND) join specifies how long Integration Server waits for 
messages from all of the destinations specified in the join. 
When a JMS trigger receives a message that satisfies part of an All (AND) join, Integration 
Server places the message in the ISInternal database. Integration Server waits for the JMS 
trigger to receive messages from the remaining destinations specified in the join. Only 
messages with the same activation ID as the first received message will satisfy the join. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 59

 4. Working with JMS Triggers

If Integration Server receives messages from all of the destinations specified in the join 
before the time‐out period elapses, Integration Server executes the service specified in the 
routing rule. If Integration Server doe not receive messages from all of the destinations 
before the time‐out period elapses, Integration Server discards the messages and writes a 
log entry. 
When the time‐out period elapses, the next message that satisfies the All (AND) join causes 
the time‐out period to start again. 

Join Time-outs for Only One (XOR) Joins

A join time‐out for an Only one (XOR) join specifies how long Integration Server discards 
instances of the other messages received from the specified destinations. 
When a JMS trigger receives a message that satisfies part of an Only one (XOR) join, 
Integration Server executes the service specified in the routing rule. Integration Server 
starts the join time‐out when the JMS trigger receives the message. For the duration of the 
time‐out period, Integration Server discards any messages the JMS trigger receives from a 
destination specified in the JMS trigger. Integration Server only discards those messages 
with the same activation ID as the first message. 
When the time‐out period elapses, the next message that the JMS trigger receives that 
satisfies the Only one (XOR) join causes the trigger service to execute and the time‐out 
period to start again. 

Setting a Join Time-out

When configuring JMS trigger properties, you can specify whether a join times out and if 
it does, what the time‐out period should be. The time‐out period indicates how long 
Integration Server waits for messages from the other destinations specified in the join after 
Integration Server receives the first message. 

Note: You need to specify a join time‐out only when the join type is All (AND) or Only one

(XOR). You do not need to specify a join time‐out for an Any (OR) join.

To set a join time-out

1 In the Navigation panel, open the JMS trigger for which you want to set the join time‐
out.
2 In the Properties panel, under General, next to Join expires, select one of the following:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 60

 4. Working with JMS Triggers

Select... To...

True  Specify that Integration Server should stop waiting for messages 
from other destinations in the join after the time‐out period 
elapses.
In the Expire after property, specify the length of the join time‐out 
period. The default join time‐out period is 1 day. 
False Specify that the join does not expire. Integration Server should 
wait indefinitely for messages from the additional destinations 
specified in the join condition. Set the Join expires property to False 
only if you are confident that all of the messages will be received 
eventually.

Important! A join is persisted across server restarts. 

3 On the File menu, click Save. 

Specifying the Execution User

For a JMS trigger, the execution user indicates which credentials Integration Server should 
use when invoking services associated with the JMS trigger. When a client invokes a 
service via an HTTP request, Integration Server checks the credentials and user group 
membership of the client against the Execute ACL assigned to the service. Integration 
Server performs this check to make sure that the client is allowed to invoke that service. 
When a JMS trigger executes, however, Integration Server invokes the service when it 
receives a message rather than as a result of a client request. Integration Server does not 
associate user credentials with a message. You can specify which credentials Integration 
Server should supply when invoking a JMS trigger service by setting an execution user for 
a JMS trigger. 
You can instruct Integration Server to invoke a service using the credentials of one of the 
predefined user accounts (Administrator, Default, Developer, Replicator). You can also 
specify a user account that you or another server administrator defined. When Integration 
Server receives a message for the JMS trigger, Integration Server uses the credentials for 
the specified user account to invoke the service specified in the routing rule. 
Make sure that the user account you select includes the credentials required by the 
execute Acts assigned to the services associated with the JMS triggers. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 61

 4. Working with JMS Triggers

To assign an execution user

1 In the Navigation panel, open the JMS trigger that you want to enable or disable.
2 In the Properties panel, under General, in the Execution user property, type the name of 
the user account whose credentials Integration Server uses to execute a service 
associated with the JMS trigger. You can specify a locally defined user account or a 
user account defined in a central or external directory.
3 On the File menu, click Save. 

Specifying Message Processing

Message processing determines how Integration Server processes the messages received 
by the JMS trigger. You can specify serial processing or concurrent processing.

Serial Processing
In serial processing, Integration Server processes messages received by a JMS trigger one 
after the other in the order in which the messages were received from the JMS provider. 
Integration Server uses a single thread for receiving and processing a message for a serial 
JMS trigger. Integration Server evaluates the first message it receives, determines which 
routing rule the message satisfies, and executes the service specified in the routing rule. 
Integration Server waits for the service to finish executing before processing the next 
message received from the JMS provider. 
If you want to process messages in the same order in which JMS clients sent the messages 
to the JMS provider, you will need to configure the JMS provider to ensure that messages 
are received by the JMS trigger in the same order in which the messages are published. 

Tip! If your trigger contains multiple routing rules to handle a group of messages that 
must be processed in a specific order, use serial processing. 

Concurrent Processing
In concurrent processing, Integration Server processes messages received from the JMS 
provider in parallel. That is, Integration Server processes as many messages for the JMS 
triggers as it can at the same time, using a separate server thread to process each message. 
Integration Server does not wait for the service specified in the routing rule to finish 
executing before it begins processing the next message. You can specify the maximum 
number of messages Integration Server can process concurrently. This equates to 
specifying the maximum number of server threads that can process messages for the JMS 
trigger at one time. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 62

 4. Working with JMS Triggers

Concurrent processing provides faster performance than serial processing. Integration 
Server processes the received messages more quickly because it can process more than 
one message for the trigger at a time. However, the more messages Integration Server 
processes concurrently, the more server threads it dispatches, and the more memory the 
message processing consumes. 
Additionally, for JMS triggers with concurrent processing, Integration Server does not 
guarantee that messages are processed in the order in which they are received. 

Message Processing and Message Consumers

Integration Server uses a consumer to receive messages for a JMS trigger. This consumer 
encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session. The type of 
message processing affects how Integration Server uses consumers to receive messages.
Serial JMS triggers have one consumer and will use one thread from the server thread 
pool to receive and process a message.
Concurrent JMS triggers use a pool of consumers to receive and process messages. Each 
consumer uses one thread from the server thread pool to receive and process a message. 
For a concurrent JMS trigger, the Max execution threads property specifies how many 
threads can be used to process messages for the trigger at one time. For concurrent JMS 
triggers, Integration Server also dedicates a thread to managing the pool of consumers. 
Consequently, the maximum number of threads that can be used by a JMS trigger is equal 
to the Max execution threads value plus 1. For example, a concurrent JMS trigger configured 
to process up to 10 messages at a time can use a maximum of 11 server threads. 

Processing Messages in Batches

You can configure a JMS trigger and its associated trigger service to process a group or 
“batch” of messages at one time. Batch processing can be an effective way of handling a 
high volume of small messages for the purposes of persisting them or delivering them to 
another back‐end resource. For example, you might want to take a batch of messages, 
create a packet of SAP IDocs, and send the packet to SAP with a single call. Alternatively, 
you might want to insert multiple messages into a database at one time using only one 
insert. The trigger service processes the messages as a unit as opposed to in a series.
The Max batch messages property indicates the maximum number of messages that the 
trigger service can receive at one time. For example, if the Max batch messages property is 
set to 5, Integration Server passes the trigger service up to 5 messages received by the JMS 
trigger to process during a single execution. 
Integration Server uses one consumer to receive and process a batch of messages. During 
pre‐processing, Integration Server checks the maximum delivery count for each message 
and, if exactly‐once processing is configured, determines whether or not the message is a 
duplicate. Integration Server then bundles the message into a single IData and passes it to 
the trigger service. If the message has exceeded the maximum delivery count or is a 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 63

 4. Working with JMS Triggers

duplicate message, Integration Server does not include it in the message batch sent to the 
trigger service. 

Note: The watt.server.jms.trigger.maxDeliveryCount property determines the 
maximum number of times the JMS provider can deliver a message to a JMS trigger. 

Integration Server acknowledges all the messages received in a batch from the JMS 
provider at one time. This includes messages that failed pre‐processing. According to the 
Java Message Service, Version 1.1, when a client acknowledges one message, the client 
acknowledges all of the messages received by the session. Because Integration Server uses 
a consumer that includes a javax.jms.MessageConsumer and a javax.jms.Session, when 
Integration Server acknowledges one message in the batch, it effectively acknowledges all 
the messages received in the batch. 
If a batch of messages is not acknowledged or they are recovered back to the JMS 
provider, the JMS provider can redeliver all of the messages in the batch to the JMS 
trigger. However, when using the webMethods JMS Provider, Integration Server can 
acknowledge individual messages that fail pre‐processing. 
When configuring JMS trigger for batch processing, keep the following in mind:
The trigger service must be coded to handle multiple messages as input. That is, the 
trigger service must use the pub.jms.batchTriggerSpec as the service signature.
When receiving a batch of messages, Integration Server evaluates the local filter in the 
routing rule against the first message in the batch only. 
The JMS trigger must not be part of a transaction. The JMS connection alias specified 
by the trigger must have a transaction type of NO TRANSACTION. 
A JMS trigger that contains an All (AND) or Only one (XOR) join cannot use batch 
processing. 

Configuring Message Processing

Use the following procedure to configure message processing for a JMS trigger.

To configure message processing for a JMS trigger

1 In the Navigation panel, open the JMS trigger for which you want to specify message 
processing.
2 In the Properties panel, next to Processing mode, select one of the following:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 64

 4. Working with JMS Triggers

Select... To...

Serial Specify that Integration Server should process messages received 
by the trigger one after the other. 
Concurrent Specify that Integration Server should process multiple messages 
for this trigger at one time. 
In the Max execution threads property, specify the maximum number 
of messages that Integration Server can process concurrently. 

3 If you want this trigger to perform batch processing, next to Max batch messages, 

specify the maximum number of messages that the trigger service can receive at one 
time. If you do not want the trigger to perform batch processing, leave this property 
set to 1. The default is 1. 

Important! For a transacted JMS trigger, Max batch messages must be set to 1. For more 

information about transacted JMS triggers, see Chapter 5, “Building a Transacted JMS 
Trigger”.

4 On the File menu, click Save.

Handling Fatal Errors for Non-Transacted JMS Triggers

You can specify that Integration Server suspend a JMS trigger automatically if a fatal error 
occurs during trigger service execution. A fatal error occurs when the trigger service ends 
because of an exception. 
If a trigger service ends because of an exception, and you configured the JMS trigger to 
suspend on fatal errors, Integration Server suspends the trigger and acknowledges the 
message to the JMS provider. The JMS trigger remains suspended until one of the 
following occurs:
You enable the trigger using the pub.trigger:enableJMSTriggers service.

You enable the trigger using Integration Server Administrator.

Integration Server restarts or the package containing the trigger reloads. (When 
Integration Server suspends a trigger because of a fatal error, Integration Server 
considers the change to be temporary. For more information about temporary vs. 
permanent state changes for triggers, see the webMethods Integration Server 
Administrator’s Guide.)
Automatic suspension of a trigger can be especially useful for serial triggers that are 
designed to process a group of messages in a particular order. If the trigger service ends in 
error while processing the first message, you might not want the trigger to proceed with 
processing the subsequent messages in the group. If Integration Server automatically 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 65

 4. Working with JMS Triggers

suspends the trigger, you have an opportunity to determine why the trigger service did 
not execute successfully.
You can handle the exception that causes the fatal error by configuring Integration Server 
to generate JMS retrieval failure events for fatal errors and by creating an event handler 
that subscribes to JMS retrieval failure events. Integration Server passes the event handler 
the contents of the JMS message as well as information about the exception. For more 
information about JMS retrieval failure events, see “Generating Events for JMS Retrieval 
Failure” on page 72.
Integration Server handles fatal errors for transacted JMS differently than for non‐
transacted JMS triggers. For information about fatal error handling for transacted JMS 
triggers, see “Handling Fatal Errors for Transacted JMS Triggers” on page 80.   

To configure fatal error handling

1 In the Navigation panel, open the JMS trigger for which you want to specify 
document processing.
2 In the Properties panel, under Fatal error handling, set the Suspend on error property to 
True if you want Integration Server to suspend the trigger when a trigger service ends 
with an error. Otherwise, select False. The default is False.
3 On the File menu, click Save.

Handling Transient Errors for Non-Transacted JMS Triggers

When building a JMS trigger, you can specify what action Integration Server takes when 
the trigger service fails because of a transient error caused by a run‐time exception. A 
transient error is an error that arises from a temporary condition that might be resolved or 
corrected quickly, such as the unavailability of a resource due to network issues or failure 
to connect to a database. Because the condition that caused the trigger service to fail is 
temporary, the trigger service might execute successfully if Integration Server waits and 
then re‐executes the service. 
A run‐time exception (specifically, an ISRuntimeException) occurs in the following 
situations:
The trigger service catches and wraps a transient error and then re‐throws it as an 
ISRuntimeException.
A pub.jms:send, pub.jms:sendAndWait, or pub.jms:reply service fails because a resource (such 
as the JNDI provider or JMS provider) is not available.
If the JMS provider is not available, and the settings for the pub.jms* service indicate 
that Integration Server should write messages to the client side queue, Integration 
Server does not throw an ISRuntimeException. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 66

 4. Working with JMS Triggers

A transient error occurs on the back‐end resource for an adapter service. Adapter 
services built on Integration Server 6.0 or later, and based on the ART framework, 
detect and propagate exceptions that signal a retry automatically if a transient error is 
detected on their back‐end resource.
You can configure transient error handling for a trigger to instruct Integration Server how 
and when to retry the trigger service. The following sections provide more information 
about configuring retry behavior for transient errors. 
For information about configuring transient error handling for JMS triggers that are part 
of a transaction, see Chapter 5, “Building a Transacted JMS Trigger”.

Configuring Retry Behavior for Trigger Services

When you configure transient error handling for a non‐transacted JMS trigger, you specify 
the following retry behavior: 
Whether Integration Server should retry trigger services for the trigger. Keep in mind 
that a trigger service can retry only if it is coded to throw ISRuntimeExceptions. For 
more information, see “Service Requirements for Retrying a Trigger Service” on 
page 67.
The maximum number of retry attempts Integration Server should make for each 
trigger service. 
If you do not want to retry a trigger service, make sure that the Max retry attempts term 
is set to 0. This may improve performance. 
The time interval between retry attempts.

How to handle a retry failure. That is, you can specify what action Integration Server 
takes if all the retry attempts are made and the trigger service still fails because of an 
ISRuntimeException. For more information about handling retry failures, see 
“Handling Retry Failure” on page 68.
The following sections provide more information about configuring the trigger service to 
throw ISRuntimeExceptions, determining the best option for handling retry failure, and 
configuring the retry properties for a trigger. 

Service Requirements for Retrying a Trigger Service

To be eligible for retry, the trigger service must do one of the following to catch a transient 
error and re‐throw it as an ISRuntimeException:
If the trigger service is a flow service, the trigger service must invoke 
pub.flow:throwExceptionForRetry. For more information about the 
pub.flow:throwExceptionForRetry, see the webMethods Integration Server Built‐In Services 
Reference. For more information about building a service that throws an exception for 
retry, see the webMethods Developer User’s Guide.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 67

 4. Working with JMS Triggers

If the trigger service is written in Java, the service can use 
com.wm.app.b2b.server.ISRuntimeException(). For more information about 
constructing ISRuntimeExceptions in Java services, see the webMethods Integration 
Server Java API Reference for the com.wm.app.b2b.server.ISRuntimeException class.
When a service invokes a pub.jms* service that sends a JMS message and the service fails 
because a resource needed by the pub.jms* service is not available, Integration Server 
automatically detects and propagates an ISRuntimeException. 
Adapter services built on Integration Server 6.0 or later, and based on the ART 
framework, detect and propagate exceptions that signal a retry if a transient error is 
detected on their back‐end resource. This behavior allows for the automatic retry when 
the service functions as a trigger service.

Note: Integration Server does not retry a trigger service that fails because a service 
exception occurred. A service exception indicates that there is something functionally 
wrong with the service. A service can throw a service exception using the EXIT step. For 
more information about the EXIT step, see the webMethods Developer User’s Guide.

Handling Retry Failure

Retry failure occurs when Integration Server makes the maximum number of retry 
attempts and the trigger service still fails because of an ISRuntimeException. When you 
configure retry properties, you can specify one of the following actions to determine how 
Integration Server handles retry failure for a trigger. 
Throw exception. When Integration Server exhausts the maximum number of retry 
attempts, Integration Server treats the last trigger service failure as a service error. 
This is the default behavior.
Suspend and retry later. When Integration Server reaches the maximum number of retry 
attempts, Integration Server suspends the trigger and then retries the trigger service 
at a later time. 
The following sections provide more information about each option for handling retry 
failures.

Overview of Throw Exception

The following table provides an overview of how Integration Server handles retry failure 
when the Throw exception option is selected. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 68

 4. Working with JMS Triggers

Step Description

1 Integration Server makes the final retry attempt and the trigger service fails 
because of an ISRuntimeException. 

2 Integration Server treats the last trigger service failure as a service 
exception.

3 Integration Server rejects the message.
If the message is persistent, Integration Server returns an acknowledgement 
to the JMS provider. 

4 Integration Server generates a JMS retrieval failure event if the 
watt.server.jms.trigger.raiseEventOnRetryFailure property is set 
to true (the default).   

5 If the JMS trigger is configured to suspend on error when a fatal error 
occurs, Integration Server suspends the JMS trigger. Otherwise, Integration 
Server processes the next message for the JMS trigger. 

In summary, the default retry failure behavior (Throw exception) rejects the message and 
allows the trigger to continue with message processing when retry failure occurs for a 
trigger service. 

Overview of Suspend and Retry Later

The following table provides more information about how the Suspend and retry later 
option works.

Step Description

1 Integration Server makes the final retry attempt and the trigger service fails 
because of an ISRuntimeException. 

2 Integration Server suspends the JMS trigger temporarily. 

Note: The change to the trigger state is temporary. Message processing will 
resume for the trigger if Integration Server restarts, the trigger is enabled or 
disabled, or the package containing the trigger reloads. You can also enable 
triggers manually using Integration Server Administrator or by invoking the 
pub.trigger:enableJMSTriggers service. 

3 Integration Server recovers the message back to the JMS provider. This 
indicates that the required resources are not ready to process the message 
and makes the message available for processing at a later time. For serial 
triggers, it also ensures that the message maintains its position at the top of 
trigger queue. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 69

 4. Working with JMS Triggers

Step Description

4 Optionally, Integration Server schedules and executes a resource monitoring 
service. A resource monitoring service is a service that you create to determine 
whether the resources associated with a trigger service are available. A 
resource monitoring service returns a single output parameter named 
isAvailable. 

5 If the resource monitoring service indicates that the resources are available 
(that is, the value of isAvailable is true), Integration Server enables the trigger. 
Message processing and message retrieval resume for the JMS trigger. 
If the resource monitoring service indicates that the resources are not 
available (that is, the value of isAvailable is false), Integration Server waits a 
short time interval (by default, 60 seconds) and then re‐executes the resource 
monitoring service. Integration Server continues executing the resource 
monitoring service periodically until the service indicates the resources are 
available. 

Tip! You can change the frequency with which the resource monitoring 
service executes by modifying the value of the 
watt.server.jms.trigger.monitoringInterval property. 

6 After Integration Server resumes the JMS trigger, Integration Server passes 
the message to the trigger. The trigger and trigger service process the 
message just as they would any message received by the JMS trigger. 

Note: At this point, the retry count is set to 0 (zero). 

In summary, the Suspend and retry later option provides a way to resubmit the message 

programmatically. It also prevents the trigger from retrieving and processing other 
messages until the cause of the transient error condition has been remedied. 

Configuring Transient Error Handling

Use the following procedure to configure transient error handling and retry behavior for a 
JMS trigger.

To configure transient error handling for a JMS trigger

1 In the Navigation panel, open the JMS trigger for which you want to configure retry 
behavior.
2 In the Properties panel, under Transient error handling, in the Max retry attempts field, 
specify the maximum number of times Integration Server should attempt to 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 70

 4. Working with JMS Triggers

re‐execute the trigger service. The default is 0 retries (the trigger service does not 
retry). 
3 In the Retry interval property, specify the time period the Integration Server waits 
between retry attempts. The default is 10 seconds.
4 Set the On retry failure property to one of the following:

Select... To...

Throw exception Specify that Integration Server should throw a 

service exception when the last allowed retry attempt 
ends because of an ISRuntimeException. 
This is the default.
For more information about the Throw exception 
option, see “Overview of Throw Exception” on 
page 68.
Suspend and retry later Specify that Integration Server should recover the 
message back to the JMS provider and suspend the 
trigger when the last allowed retry attempt ends 
because of an ISRuntimeException. For more 
information about the Suspend and retry later option, 
see “Overview of Suspend and Retry Later” on 
page 69.

Note: If you want Integration Server to automatically 
enable the trigger when the trigger’s resources 
become available, you must provide a resource 
monitoring service that Integration Server can 
execute to determine when to resume the trigger. For 
more information about building a resource 
monitoring service, see Appendix B, “Building a 
Resource Monitoring Service”.

5 If you selected Suspend and retry later, then in the Resource monitoring service property 

specify the service that Integration Server should execute to determine the availability 
of resources associated with the trigger service. Multiple triggers can use the same 
resource monitoring service. For information about building a resource monitoring 
service, see “Building a Resource Monitoring Service” on page 115.
6 On the File menu, click Save.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 71

 4. Working with JMS Triggers

Notes:
Triggers and services can both be configured to retry. When a trigger invokes a service 
(that is, the service functions as a trigger service), Integration Server uses the trigger 
retry properties instead of the service retry properties. 
When Integration Server retries a trigger service and the trigger service is configured 
to generate audit data on error, Integration Server adds an entry to the audit log for 
each failed retry attempt. Each of these entries will have a status of “Retried” and an 
error message of “Null”. However, if Integration Server makes the maximum retry 
attempts and the trigger service still fails, the final audit log entry for the service will 
have a status of “Failed” and will display the actual error message. Integration Server 
makes the audit log entry regardless of which retry failure option the trigger uses. 
Integration Server generates the following journal log message between retry 
attempts: 
[ISS.0014.0031D] Service serviceName failed with ISRuntimeException. Retry x of y will 
begin in retryInterval milliseconds.
If you do not configure service retry for a trigger, set the Max retry attempts property to 
0. Because managing service retries creates extra overhead, setting this property to 0 
can improve the performance of services invoked by the trigger.
You can invoke the pub.flow:getRetryCount service within a trigger service to determine 
the current number of retry attempts made by Integration Server and the maximum 
number of retry attempts allowed for the trigger service. For more information about 
the pub.flow:getRetryCount service, see the webMethods Integration Server Built‐In Services 
Reference.

Generating Events for JMS Retrieval Failure

By default, Integration Server generates JMS retrieval failure events when errors occur 
during message retrieval and JMS trigger processing. You can build event handlers that 
subscribe to and handle the JMS retrieval failure events. 
A JMS retrieval failure event occurs in the following situations:
A trigger service executed by a JMS trigger throws a non‐transient error and the 
watt.server.jms.trigger.raiseEventOnException property is set to true (the 
default).
A trigger service associated with a JMS trigger ends because of a transient error, all 
retry attempts have been made, and the JMS trigger is configured to throw an 
exception on retry failure. In addition, the 
watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the 
default).   

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 72

 4. Working with JMS Triggers

The maximum delivery count from the JMS provider has been met for the message 
and the watt.server.jms.trigger.raiseEventOnRetryFailure property is set to 
true (the default).
The watt.server.jms.trigger.maxDeliveryCount property specifies the 
maximum number of times the JMS provider can deliver a message to Integration 
Server. The default is 100. In a JMS message, the property JMSXDeliveryCount 
specifies the number of times the JMS provider delivered the message. Most JMS 
providers set this value. 
While performing exactly‐once processing, the connection to the document history 
database is unavailable, and transient error handling for the JMS trigger is configured 
to Throw exception (non‐transacted JMS trigger) or Recover only (transacted JMS 
trigger). In addition, the watt.server.jms.trigger.raiseEventOnRetryFailure 
property is set to true (the default). 
While performing exactly‐once processing, the document resolver service ends with 
an ISRuntimeException, and transient error handling for the JMS trigger is configured 
to Throw exception (non‐transacted JMS trigger) or Recover only (transacted JMS 
trigger). In addition, the watt.server.jms.trigger.raiseEventOnRetryFailure 
property is set to true (the default). 
While performing exactly‐once processing, the document resolver service ends with 
an exception other than an ISRuntimeException. In addition, the 
watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the 
default). 
A service that functions as an event handler for a JMS retrieval failure event should use 
the pub.event:jmsReceiveErrorEvent specification as its service signature. For more information 
about the pub.event:jmsReceiveErrorEvent specification, see the webMethods Integration Server 
Built‐In Services Reference. For more information about building event handlers, see the 
webMethods Developer User’s Guide.

Debugging a JMS Trigger

Integration Server provides a server configuration property that you can use to produce 
an extra level of verbose logging. You can enable debug trace logging for all JMS triggers 
or for individual JMS triggers.

To enable debug trace logging for all JMS triggers

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Extended.
3 Click Edit Extended Settings.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 73

 4. Working with JMS Triggers

4 Under Extended Settings, type the following:
watt.server.jms.debugTrace=true

5 Click Save Changes.
6 Suspend and then enable all JMS triggers. 
For information about suspending and enabling all JMS triggers at one time, see 
“Enabling, Disabling, and Suspending JMS Triggers” on page 106. 

To enable debug trace logging for a specific JMS trigger

1 Open Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Extended.
3 Click Edit Extended Settings.
4 Under Extended Settings, type the following:
watt.server.jms.debugTrace.triggerName=true

Where triggerName is the fully qualified name of the trigger in the format 
folder.subfolder:triggerName.
5 Click Save Changes.
6 Disable and then enable the trigger.
For more information about enabling and disabling JMS triggers using Developer, see 
“Enabling or Disabling a JMS Trigger” on page 57. For information about enabling 
and disabling JMS triggers using Integration Server Administrator, see “Enabling, 
Disabling, and Suspending JMS Triggers” on page 106.

Building JMS Triggers with Multiple Routing Rules

A JMS trigger can contain more than one routing rule. Each routing rule can specify a 
different local filter and a different service to invoke. 
You might create multiple routing rules so that a JMS trigger processes a group of 
messages in a specific order. Each routing rule might execute a different trigger service 
based on the contents or type of message received. When a JMS trigger receives a 
message, Integration Server determines which service to invoke by evaluating the local 
filters for each routing rule. 
Integration Server evaluates the routing rules in the same order in which the rules appear 
in the editor. It is possible that a message could satisfy more than one routing rule. 
However, Integration Server executes only the service associated with the first satisfied 
routing rule and ignores the remaining routing rules. Therefore, the order in which you 
list routing rules on the editor is important. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 74

 4. Working with JMS Triggers

You might want to use multiple routing rules to control service execution when a service 
that processes a message depends on successful execution of another service. For 
example, to process a purchase order, you might create one service that adds a new 
customer record to a database, another that adds a customer order, and a third that bills 
the customer. The service that adds a customer order can only execute successfully if the 
new customer record has been added to the database. Likewise, the service that bills the 
customer can only execute successfully if the order has been added. You can ensure that 
the services execute in the necessary order by creating a trigger that contains one routing 
rule for each expected message.
Use the following general guidelines to build a JMS trigger that performs ordered service 
execution.
Because the JMS provider cannot guarantee message order across destinations, the 
JMS trigger must specify a single destination. That is, the JMS trigger cannot include a 
join. 
Each routing rule, except the last one, must contain a local filter. For example, you 
might create a filter based on a custom property that the sending client adds to the 
message. Integration Server uses the local filters to differentiate between the 
messages. Without a local filter, only the first routing rule would ever execute. 
Routing rules must appear in the order in which you want the messages to be 
processed. Each routing rule must have a unique name.
Set the Processing mode property to serial to ensure that the Integration Server 
processes the messages in the same order in which the JMS trigger receives them. 
Serial processing ensures that the services that process the messages do not execute at 
the same time. 
Set Max batch messages to 1 (the default). When a trigger service processes a batch of 
messages, Integration Server only applies the filter to the first message in the batch.

Important! Messages must be sent to JMS provider in the same order in which you want the 
messages to be processed. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 75

 4. Working with JMS Triggers

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 76

Chapter 5. Building a Transacted JMS Trigger

What Is a Transacted JMS Trigger? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Overview of Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Handling Fatal Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Handling Transient Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 77

 5. Building a Transacted JMS Trigger

What Is a Transacted JMS Trigger?

A transacted JMS trigger is a JMS trigger that executes within a transaction. A transaction is 
a logical unit of work composed of one or more interactions with one or more resources. 
The interactions within a transaction are either all committed or all rolled back. A 
transaction either entirely succeeds or has no effect at all. 
For a transacted JMS trigger, Integration Server uses a transacted JMS connection alias to 
receive messages from the JMS provider and to process the messages. A JMS connection 
alias is considered to be transacted when it has a transaction type of XA TRANSACTION 
or LOCAL TRANSACTION. 
The execution of a transacted JMS trigger is an implicit transaction. In an implicit 
transaction, Integration Server starts and completes the transaction automatically, without 
the need for executing any of the transaction management services.
Integration Server starts the implicit transaction when it uses the specified transacted JMS 
connection alias to connect to the JMS provider and receive messages for the transacted 
JMS trigger. Integration Server implicitly commits or rolls back the transaction based on 
the success or failure of the trigger service.
Integration Server commits the transaction if the trigger service executes successfully.

Integration Server rolls back the transaction if the trigger service fails with an 
ISRuntimeException (a transient error). For detailed information about how 
Integration Server handles a transient error within a transaction, see “Handling 
Transient Errors for Transacted JMS Triggers” on page 82. 
Integration Server rolls back the transaction if the trigger service fails with a Service 
Exception (a fatal error). For detailed information about how Integration Server 
handles a fatal error within a transaction, see “Handling Fatal Errors for Transacted 
JMS Triggers” on page 80. 
Because Integration Server handles the transaction implicitly, you do not need to use any 
of the transaction management services, such as pub.art.transaction:startTransaction, in the 
trigger service. However, if the trigger service includes a nested transaction, you can use 
the transaction management services to explicitly manage the nested transaction. 

Overview of Building a Transacted JMS Trigger

Like a non‐transacted JMS trigger, a transacted JMS trigger specifies a destination from 
which it would like to receive documents and specifies routing rules to process messages 
it receives. However, a transacted JMS trigger has some prerequisites as well as some 
properties that are different from a non‐transacted JMS trigger. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 78

 5. Building a Transacted JMS Trigger

Prerequisites for a Transacted JMS Trigger

Before you build a transacted JMS trigger, make sure the following points are true:
A transacted JMS connection alias exists. A JMS connection alias is considered to be 
transacted when it has a transaction type of XA TRANSACTION or LOCAL 
TRANSACTION. 
The WmART package is installed and enabled. 

Properties for Transacted JMS Triggers

Integration Server and Developer provide different properties for a transacted JMS trigger 
than for a non‐transacted JMS trigger. The following list identifies properties that are 
specific to transacted JMS triggers, specific to non‐transacted JMS triggers, or apply to 
both but must be set to a particular value for transacted JMS triggers. 
For transacted JMS triggers, message acknowledgement is handled by the transaction; 
the acknowledgement mode does not apply. Consequently, Developer does not 
display the Acknowledgement mode property for a transacted JMS trigger. 
A transacted JMS trigger can only use Any (OR) joins, for which you do not need to 
specify a join time‐out. Because All (AND) and Only one (XOR) joins cannot be used, 
Developer does not display the Join expires and Expire after properties for a transacted 
JMS trigger. 
A transacted JMS trigger can process one message at a time. It cannot process batches 
of messages. Make sure that the Max batch processing property is set to 1. 
Because a transaction is an all or nothing situation, a trigger service cannot retry a 
message if a trigger service ends because of a transient error. Developer does not 
display the retry properties (Max retry attempts, Retry interval, and On retry failure) for a 
transacted JMS trigger.
You can specify how Integration Server handles a transient error that causes the 
transaction to be rolled back. Developer displays an On transaction rollback property 
that you can use to specify whether Integration Server simply recovers the message 
from the JMS provider or whether it suspends the JMS trigger in addition to 
recovering the message. For more information about transient error handling for 
transacted JMS triggers, see “Handling Transient Errors for Transacted JMS Triggers” 
on page 82.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 79

 5. Building a Transacted JMS Trigger

Steps for Building a Transacted JMS Trigger

Building a transacted JMS trigger is a process that involves the following basic stages.

Stage Description

1 Create a new JMS trigger on Integration Server.

2 Specify a JMS connection alias with a transaction type of XA 
TRANSACTION or LOCAL TRANSACTION. 

3 Specify the destination (queues or topics) on the JMS provider from which 
you want to receive messages. You also specify any message selectors that 
you want the JMS provider to use to filter messages for the JMS trigger.

4 Create routing rules and specify the services that Integration Server 
invokes when the JMS trigger receives messages.

5 Set the following JMS trigger properties: 

Property name... For additional information, see...

Enabled “Enabling or Disabling a JMS Trigger” on 
page 57
Execution user “Specifying the Execution User” on page 61
Message processing “Specifying Message Processing” on page 62
Fatal error handling “Handling Fatal Errors for Transacted JMS 
Triggers” on page 80
Transient error handling “Handling Transient Errors for Transacted JMS 
Triggers” on page 82
Exactly once Chapter 6, “Exactly‐Once Processing for JMS 
Triggers”
Permissions webMethods Developer User’s Guide

6 Test and debug the JMS trigger. For more information, see “Debugging a 
JMS Trigger” on page 73. 

Handling Fatal Errors for Transacted JMS Triggers

You can specify that Integration Server suspend a transacted JMS trigger automatically if a 
fatal error occurs during trigger service execution. A fatal error occurs when the trigger 
service ends because of a Service Exception. 
When a transacted trigger is configured to suspend when a fatal error occurs, Integration 
Server does the following when the trigger service ends with a Service Exception:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 80

 5. Building a Transacted JMS Trigger

Step Description

1 The trigger service for a transacted JMS trigger fails because of a Service 
Exception. 

2 Integration Server rolls back the entire transaction and Integration Server 
recovers the message back to the JMS provider. The JMS provider marks the 
message as redelivered and increments the value of the JMSXDeliveryCount 
property in the JMS message. 

3 If the JMS trigger is configured to use a document history database for 
exactly‐once processing, Integration Server adds an entry with a status of 
“completed” for the message to the document history database. 
Because Integration Server does not acknowledge the message when it is 
rolled back, the JMS provider makes the message available for redelivery to 
the JMS trigger. However, a message that causes a trigger service to end 
because of a Service Exception typically does not process successfully upon 
redelivery. Integration Server adds the “completed” entry so that the 
message is treated as a duplicate when it is received from the JMS provider. 
The message is rejected after it is resent.   
If the JMS trigger does not use a document history database, Integration 
Server continues to receive and attempt message processing until the 
message processes successfully or the maximum delivery count has been 
met. The maximum delivery count determines the maximum number of 
time the JMS provider can deliver the message to the JMS trigger. It is 
controlled by the watt.server.jms.trigger.maxDeliveryCount 
property. 

4 Integration Server suspends the JMS trigger. 

5 The JMS trigger remains suspended until one of the following occurs:
You enable the trigger using the pub.trigger:enableJMSTriggers service.

You enable the trigger using Integration Server Administrator.

Integration Server restarts or the package containing the trigger 
reloads. (When Integration Server suspends a trigger because of a fatal 
error, Integration Server considers the change to be temporary. For 
more information about temporary vs. permanent state changes for 
triggers, see the webMethods Integration Server Administrator’s Guide.)

You can handle the exception that causes the fatal error by configuring Integration Server 
to generate JMS retrieval failure events for fatal errors and by creating an event handler 
that subscribes to JMS retrieval failure events. Integration Server passes the contents of the 
JMS message and exception information to the event handler. For more information about 
JMS retrieval failure events, see “Generating Events for JMS Retrieval Failure” on page 72.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 81

 5. Building a Transacted JMS Trigger

To configure fatal error handling for a transacted JMS trigger

1 In the Navigation panel, open the JMS trigger for which you want to specify 
document processing.
2 In the Properties panel, under Fatal error handling, set the Suspend on error property to 
True if you want Integration Server to suspend the trigger when a trigger service ends 
with an error. Otherwise, select False. The default is False.
3 Configure exactly‐once processing for the JMS trigger. For more information about 
configuring exactly‐once processing, see “Configuring Exactly‐Once Processing” on 
page 99.
4 On the File menu, click Save.

Handling Transient Errors for Transacted JMS Triggers

When building a transacted JMS trigger, you can specify what action Integration Server 
takes when a transient error causes a trigger service to fail and the entire transaction is 
rolled back. 
A transient error is an error that arises from a temporary condition that might be resolved 
or corrected quickly, such as the unavailability of a resource due to network issues or 
failure to connect to a database. A transient error is caused by a run‐time exception. A run‐
time exception (specifically, an ISRuntimeException) occurs in the following situations. 
The trigger service catches and wraps a transient error and then re‐throws it as an 
ISRuntimeException. 
The pub.jms:send, pub.jms:sendAndWait, or pub.jms:reply service fails because a resource 
(such as the JNDI provider or JMS provider) is not available.
If the JMS provider is not available, and the settings for the pub.jms* service indicate 
that Integration Server should write messages to the client side queue, Integration 
Server does not throw an ISRuntimeException. 
A transient error occurs on the back‐end resource for an adapter service. Adapter 
services built on Integration Server 6.0 or later, and based on the ART framework, 
detect and propagate exceptions that signal a retry automatically if a transient error is 
detected on their back‐end resource.
You can specify one of the following transient error handling options for a transacted JMS 
trigger:
Recover only. After a transaction is rolled back, Integration Server receives the message 
from the JMS provider almost immediately. This is the default.
Suspend and recover. After a transaction is rolled back, Integration Server suspends the 
JMS trigger and receives the message from the JMS provider at a later time. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 82

 5. Building a Transacted JMS Trigger

The following sections provide an overview of how Integration Server acts in each 
situation.

Overview of Recover Only

The following table provides an overview of how Integration Server handles transaction 
rollback when the Recover Only option is selected for a transacted JMS trigger. 

Step Description

1 The trigger service fails because of an ISRuntimeException. 

2 Integration Server rolls back the entire transaction. 
When the transaction is rolled back, Integration Server recovers the 
message back to the JMS provider automatically. The JMS provider marks 
the message as redelivered and increments the delivery count 
(JMSXDeliveryCount field in the JMS message).
At this point, a JMS provider typically makes the message available for 
immediate redelivery. 

3 Integration Server receives the same message from the JMS provider and 
processes the message. 
Because Integration Server receives the message almost immediately after 
transaction roll back, it is likely that the temporary condition that caused 
the ISRuntimeException has not resolved and the trigger service will end 
with a transient error again. Consequently, setting On transaction rollback to 
Recover only could result in wasted processing. 

Note: Integration Server enforces a maximum delivery count, which 
determines the maximum number of time the JMS provider can deliver the 
message to the JMS trigger. If the maximum delivery count has been met, 
the JMS provider will not deliver the message to the JMS trigger. Instead, 
the JMS provider will acknowledge and remove the message. The 
maximum delivery count is controlled by the 
watt.server.jms.trigger.maxDeliveryCount property. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 83

 5. Building a Transacted JMS Trigger

Overview of Suspend and Recover

The following table provides an overview of how Integration Server handles transaction 
rollback when the Suspend and recover option is selected for a transacted JMS trigger.

Step Description

1 The trigger service fails because of an ISRuntimeException. 

2 Integration Server rolls back the entire transaction. 
When the transaction is rolled back, Integration Server recovers the message 
back to the JMS provider automatically. The JMS provider marks the message 
as redelivered and increments the delivery count (JMSXDeliveryCount field in 
the JMS message).

3 Integration Server suspends the JMS trigger temporarily. 
The JMS trigger is suspended on this Integration Server only. If the 
Integration Server is part of a cluster, other servers in the cluster can retrieve 
and process messages for the trigger. 

Note: The change to the trigger state is temporary. Message processing will 
resume for the trigger if Integration Server restarts, the trigger is enabled or 
disabled, or the package containing the trigger reloads. You can also enable 
triggers manually using Integration Server Administrator or by invoking the 
pub.trigger:enableJMSTriggers service. 

4 Optionally, Integration Server schedules and executes a resource monitoring 
service. A resource monitoring service is a service that you create to determine 
whether the resources associated with a trigger service are available. A 
resource monitoring service returns a single output parameter named 
isAvailable. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 84

 5. Building a Transacted JMS Trigger

Step Description

5 If the resource monitoring service indicates that the resources are available 
(that is, the value of isAvailable is true), Integration Server enables the trigger. 
Message processing and message retrieval resume for the JMS trigger. 
If the resource monitoring service indicates that the resources are not 
available (that is, the value of isAvailable is false), Integration Server waits a 
short time interval (by default, 60 seconds) and then re‐executes the resource 
monitoring service. Integration Server continues executing the resource 
monitoring service periodically until the service indicates the resources are 
available. 

Tip! You can change the frequency at which the resource monitoring service 
executes by modifying the value of the 
watt.server.jms.trigger.monitoringInterval property. 

6 After Integration Server resumes the JMS trigger, Integration Server receives 
the message from the JMS provider and processes the message. 

Note: If the maximum delivery count has been met, the JMS provider will not 
deliver the message to the JMS trigger. The maximum delivery count 
determines the maximum number of time the JMS provider can deliver the 
message to the JMS trigger. It is controlled by the 
watt.server.jms.trigger.maxDeliveryCount property. 

Configuring Transient Error Handling for a Transacted JMS

Trigger
Use the following procedure to configure how Integration Server responds when a 
transaction is rolled back due to a transient error that occurs during processing of a 
transacted JMS trigger.

To configure transient error handling for a transacted JMS trigger

1 In the Navigation panel, open the trigger for which you want to configure transient 
error handling.
2 In the Properties panel, under Transient error handling, in the On transaction rollback 
property, select one of the following:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 85

 5. Building a Transacted JMS Trigger

Select... To...

Recover only Specify that Integration Server recovers the message after a 

transaction is rolled back due to a transient error.
This is the default.
For more information about the Recover only option, see 
“Overview of Recover Only” on page 83.
Suspend and recover Specify that Integration Server does the following after a 
transaction is rolled back due to a transient error:
Suspends the JMS trigger 

Recovers the message after a resource monitoring 
service indicates that the resources needed by the 
trigger service are available
For more information about the Suspend and recover option, 
see “Overview of Suspend and Recover” on page 84.

3 If you selected Suspend and recover, in the Resource monitoring service property, specify 

the service that Integration Server should execute to determine the availability of 
resources associated with the trigger service. Multiple triggers can use the same 
resource monitoring service. For information about building a resource monitoring 
service, see Appendix B, “Building a Resource Monitoring Service”.
4 On the File menu, click Save.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 86

Chapter 6. Exactly-Once Processing for JMS Triggers

Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Duplicate Detection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 87

 6. Exactly-Once Processing for JMS Triggers

Overview of Exactly-Once Processing

Within Integration Server, exactly‐once processing is a facility that ensures one‐time 
processing of a persistent message by a JMS trigger. The trigger does not process 
duplicates of the message. Integration Server provides exactly‐once processing when all 
of the following are true:
The message is persistent. 

The JMS trigger has an acknowledgement mode set to CLIENT_ACKNOWLEDGE.

Exactly‐once properties are configured for the JMS trigger. 

Duplicate Detection Methods

Integration Server ensures exactly‐once processing by performing duplicate detection and 
by providing the ability to retry trigger services. Duplicate detection determines whether 
the current message is a copy of one previously processed by the trigger.
Duplicate messages can be introduced in to the webMethods system in the following 
situations:
The sending client sends the same message more than once.

When receiving persistent messages from the JMS provider, Integration Server and 
the JMS provider lose connectivity before the JMS trigger processes and 
acknowledges the message. The JMS trigger will receive the message again when the 
connection is restored. 
Integration Server uses duplicate detection to determine the message’s status. The 
message status can be one of the following:
New. The message is new and has not been processed by the trigger.

Duplicate. The message is a copy of one already processed the trigger. 

In Doubt. Integration Server cannot determine the status of the message. The trigger 
may or may not have processed the message before. 
To resolve the message status, Integration Server evaluates, in order, one or more of the 
following:
Delivery count indicates how many times the JMS provider has delivered the message 
to the JMS trigger. 
Document history database maintains a record of all persistent message IDs processed by 
JMS triggers that have an acknowledgment mode of CLIENT_ACKNOWLEDGE and for 
which exactly‐once processing is configured.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 88

 6. Exactly-Once Processing for JMS Triggers

Document resolver service is a service created by a user to determine the message status. 

The document resolver service can be used instead of or in addition to the document 
history database.
The steps that Integration Server takes to determine a message’s status depend on the 
exactly‐once properties configured for the JMS trigger. For more information about 
configuring exactly‐once properties, see “Configuring Exactly‐Once Processing” on 
page 99. 
The table below summarizes the process Integration Server follows to determine a 
message’s status and the action the server takes for each duplicate detection method.

1 Check Delivery Count 

When the trigger is configured to detect duplicates, Integration Server will 
check the message’s delivery count to determine if the JMS trigger processed the 
message previously. Specifically, Integration Server checks the value of the 
JMSXDeliveryCount property in the message. 
Delivery Count Action

1 If using document history, Integration Server proceeds 
to  2  to check the document history database.
If document history is not used, Integration Server 
considers the message to be New. Integration Server 
executes the trigger service.
>1 If using document history, Integration Server proceeds 
to  2  to check the document history database. 
If document history is not used, Integration Server 
proceeds to  3  to execute the document resolver 
service. 
If neither document history nor a document resolver 
service are used, Integration Server considers the 
message to be In Doubt.
‐1 (Undefined) If using document history, Integration Server proceeds 
to  2  to check the document history database. 
If document history is not used, Integration Server 
proceeds to  3  to execute the document resolver 
service. 
Otherwise, Integration Server considers the message to 
be New. Integration Server executes the trigger service.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 89

 6. Exactly-Once Processing for JMS Triggers

2 Check Document History

If a document history database is configured and the trigger uses it to maintain 
a record of processed messages, Integration Server checks for the message’s 
UUID in the document history database. If the message does not have a UUID, 
Integration Server uses the value of the JMSMessageID field from the message 
header.
UUID or JMSMessageID
Exists? Action

No. Message is New. Integration Server executes the trigger 
service.
Yes. Integration Server checks the processing status of the 
entry. 
If the processing status indicates that message 
processing completed, then Integration Server 
considers the message to be a Duplicate. Integration 
Server acknowledges the message, but does not 
execute trigger service.
If the processing status indicates that processing 
started but did not complete, Integration Server 
considers the message to be In Doubt. 

If provided, Integration Server proceeds to  3  to 
invoke the document resolver service. Otherwise, 
Integration Server considers the message to be In 
Doubt. Integration Server acknowledges the 
message, but does not execute the trigger service. 

3 Execute Document Resolver Service

If a document resolver service is specified, Integration Server executes the 
document resolver service assigned to the trigger.
Returned Status Action

NEW Integration Server executes the trigger service and 
acknowledges the message. 
DUPLICATE Integration Server acknowledges the message, but does 
not execute the trigger service. 
IN DOUBT Integration Server acknowledges the message, but does 
not execute the trigger service. 

The following sections provide more information about each method of duplicate 
detection. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 90

 6. Exactly-Once Processing for JMS Triggers

Delivery Count
The delivery count indicates the number of times the JMS provider has delivered or 
attempted to deliver a message to the JMS trigger. Most JMS providers track the message 
delivery count in the JMS‐defined property JMSXDeliveryCount. The initial delivery is 1, 
the second delivery is 2, and so forth. A delivery count other than 1 indicates that the 
trigger might have received and processed (or partially processed) the message before. 
For example, when Integration Server first retrieves a message for a JMS trigger, the 
JMSXDeliveryCount count is 1 (one). If a resource (JMS provider or Integration Server) 
shuts down before the trigger processes and acknowledges the message, Integration 
Server will retrieve the message again when the connection is re‐established. The second 
time Integration Server retrieves the message, the JMSXDeliveryCount will be 2. A delivery 
count greater than 1 indicates that the JMS provider may have delivered the message to 
the trigger before. 
The following table identifies the possible delivery count values and the message status 
associated with each value. 

A delivery count of... Indicates...

‐1 The JMS provider that delivered the message does not 
maintain a JMSXDeliveryCount or there was an error when 
retrieving the JMSXDeliveryCount. As a result, the delivery 
count is undefined. Integration Server uses a value of ‐1 to 
indicate that the delivery count is absent.
If other methods of duplicate detection are configured for this 
trigger (document history database or document resolver 
service), Integration Server uses these methods to determine 
the message status. If no other methods of duplicate detection 
are configured, Integration Server assigns the message a status 
of New and executes the trigger service.
1 This is the first time the JMS trigger received the message.
If the JMS trigger uses a document history to perform 
duplicate detection, Integration Server checks the document 
history database to determine the message status. If no other 
methods of duplicate detection are configured, Integration 
Server assigns the message a status of New and executes the 
trigger service. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 91

 6. Exactly-Once Processing for JMS Triggers

A delivery count of... Indicates...

> 1 The JMS provider has delivered the message more than once. 
The trigger might or might not have processed the message 
before. The delivery count does not provide enough 
information to determine whether the trigger processed the 
message before. 
If other methods of duplicate detection are configured for this 
trigger (document history database or document resolver 
service), Integration Server uses these methods to determine 
the message status. If no other methods of duplicate detection 
are configured, Integration Server assigns the message a status 
of In Doubt and acknowledges the message.

Integration Server uses delivery count to determine message status whenever you enable 
exactly‐once processing for a JMS trigger. That is, setting the Detect duplicates property to 
true indicates delivery count will be used as part of duplicate detection. 

Document History Database

The document history database maintains a history of the persistent messages processed 
by JMS triggers. Integration Server adds an entry to the document history database when 
a trigger service begins executing and when it executes to completion (whether it ends in 
success or failure). The document history database contains message processing 
information only for triggers for which the Use history property is set to true. 
The database saves the following information about each message: 
Trigger ID. Universally unique identifier for the JMS trigger processing the message. 

UUID or JMSMessageID. Universally unique identifier for the message. If the sending 

client assigned a value to the uuid field in the message, Integration Server uses the 
uuid value to identify the message. If the uuid field is empty, Integration Server uses 
the value of the JMSMessageID field in the message header to identify the message.
Processing Status. Indicates whether the trigger service executed to completion or is 
still processing the message. An entry in the document history database has either a 
status of “processing” or a status of “completed.” Integration Server adds an entry 
with a “processing” status immediately before executing the trigger service. When the 
trigger service executes to completion, Integration Server adds an entry with a status 
of “completed” to the document history database. 
Time. The time the trigger service began executing. The document history database 
uses the same time stamp for both entries it makes for a message. This allows the 
Integration Server to remove both entries for a specific message at the same time.
To determine whether a message is a duplicate of one already processed by the JMS 
trigger, Integration Server checks for the message’s UUID (or JMSMessageID) in the 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 92

 6. Exactly-Once Processing for JMS Triggers

document history database. The existence or absence of the message’s UUID 
(JMSMessageID) can indicate whether the message is new or a duplicate. 

If the UUID or JMSMessageID... Then Integration Server...

Does not exist. Assigns the message a status of New and executes the 
trigger service. The absence of the UUID (JMSMessageID) 
indicates that the trigger has not processed the message 
before. 
Exists in a “processing”  Assigns the message a status of Duplicate. The existence 
entry and a “completed”  of the “processing” and “completed” entries for the 
entry. message’s UUID (JMSMessageID) indicate the trigger 
processed the message successfully already. Integration 
Server acknowledges the message, discards it, and writes 
a journal log entry indicating that a duplicate message 
was received. 
Exists in a “processing”  Cannot determine the status of the message conclusively. 
entry only. The absence of an entry with a “completed” status for 
the UUID (JMSMessageID) indicates that the trigger 
service started to process the message, but did not finish. 
The trigger service might still be executing or the server 
might have unexpectedly shut down during service 
execution. 
If a document resolver service is specified for the JMS 
trigger, Integration Server invokes it. If a document 
resolver service is not specified, Integration Server 
assigns the message a status of In Doubt, acknowledges 
the message, and writes a journal log entry stating that 
an In Doubt message was received. 
Exists in a “completed”  Determines the message is a Duplicate. The existence of 
entry only. the “completed” entry indicates the JMS trigger 
processed the message successfully already. Integration 
Server acknowledges the message, discards it, and writes 
a journal log entry indicating that a Duplicate message 
was received.

Note: Integration Server also considers a message to be In Doubt when the value of the 
message’s UUID (or JMSMessageID) exceeds 96 characters. If specified, Integration Server 
executes the document resolver service to determine the message’s status. Otherwise, the 
Integration Server logs the message as In Doubt. 

For information about configuring the document history database, refer to the webMethods 
Installation Guide.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 93

 6. Exactly-Once Processing for JMS Triggers

What Happens When the Document History Database Is Not Available?

If the connection to the document history database is unavailable when Integration Server 
attempts to query the database, Integration Server takes one of the following actions 
depending on the transactionality of the JMS trigger and the configured transient error 
handling. 
For a non-transacted JMS trigger...

If On retry failure is set to... Integration Server does the following...

Suspend and retry later If the document history database is properly configured, 

Integration Server suspends the JMS trigger and 
schedules a system task that executes a service that checks 
for the availability of the document history database. 
Integration Server enables the trigger and re‐executes it 
when the service indicates that the document history 
database is available.
If the document history database is not properly 
configured, Integration Server suspends the trigger, but it 
does not schedule a system task to check for the database’s 
availability and it does not resume the trigger 
automatically. You must manually enable the JMS trigger 
after configuring the document history database properly. 
Throw exception Generates a JMS retrieval failure event and acknowledges 
the message.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 94

 6. Exactly-Once Processing for JMS Triggers

For a transacted JMS trigger...

If On transaction rollback is set to... Integration Server does the following...

Suspend and recover If the document history database is properly 

configured, Integration Server suspends the JMS 
trigger and schedules a system task that executes a 
service that checks for the availability of the 
document history database. Integration Server 
enables the trigger and re‐executes it when the 
service indicates that the document history database 
is available.
If the document history database is not properly 
configured, Integration Server suspends the trigger, 
but it does not schedule a system task to check for 
the database’s availability and it does not resume 
the trigger automatically. You must manually enable 
the JMS trigger after configuring the document 
history database properly. 
Recover only Generates a JMS retrieval failure event and 
acknowledges the message.

For more information about generating JMS retrieval events, see “Generating Events for 
JMS Retrieval Failure” on page 72.

Managing the Size of the Document History Database

To keep the size of the document history database manageable, Integration Server 
periodically removes expired rows from the database. The length of time the document 
history database maintains information about a UUID varies for each trigger and depends 
on the value of the trigger’s History time to live property. 
Integration Server provides a scheduled service that removes expired entries from the 
database. By default, the wm.server.dispatcher:deleteExpiredUUID service executes every 10 
minutes. You can change the frequency with which the service executes. For information 
about editing scheduled services, see the webMethods Integration Server Administrator’s Guide.

Note: The watt.server.idr.reaperInterval property determines the initial execution 
frequency for the wm.server.dispatcher:deleteExpiredUUID service. After you define a JDBC 
connection pool for Integration Server to use to communicate with the document history 
database, change the execution interval by editing the scheduled service. 

You can also use Integration Server Administrator to clear expired document history 
entries from the database immediately.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 95

 6. Exactly-Once Processing for JMS Triggers

To clear expired entries from the document history database

1 Open Integration Server Administrator.
2 From the Settings menu in the Navigation panel, click Resources.
3 Click Exactly Once Statistics.
4 Click Remove Expired Document History Entries.

Document Resolver Service

The document resolver service is a service that you build to determine whether a 
message’s status is New, Duplicate, or In Doubt. Integration Server passes the document 
resolver service some basic information that the service will use to determine message 
status, such as the trigger name and the JMS message. The document resolver service 
must return one of the following for the message status: New, In Doubt, or Duplicate. 
By using the delivery count and the document history database, Integration Server can 
assign most messages a status of New or Duplicate. However, a small window of time 
exists where checking the delivery count and the message history database might not 
conclusively determine whether a trigger processed a message before. For example:
If a duplicate message arrives before the trigger finishes processing the original 
message, the document history database does not yet contain an entry that indicates 
processing completed. Integration Server assigns the second message a status of In 
Doubt. Typically, this is only an issue for long‐running trigger services.
If Integration Server fails before completing message processing, the JMS provider 
redelivers the message. However, the document history database contains only an 
entry that indicates message processing started. Integration Server assigns the 
redelivered message a status of In Doubt. 
You can write a document resolver service to determine the status of messages received 
during these windows. How the document resolver service determines the message status 
is up to the developer of the service. Ideally, the writer of the document resolver service 
understands the semantics of all the applications involved and can use the message to 
determine the message status conclusively. If processing an earlier copy of the message 
left some application resources in an indeterminate state, the document resolver service 
can also issue compensating transactions.
If provided, the document resolver service is the final method of duplicate detection. 
For more information about building a document resolver service, see “Building a 
Document Resolver Service” on page 101.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 96

 6. Exactly-Once Processing for JMS Triggers

Document Resolver Service and Exceptions

At run time, a document resolver service might end because of an exception. How 
Integration Server proceeds depends on the type of exception and how the JMS trigger is 
configured to handle transient errors. 
If the document resolver service ends with an ISRuntimeException, and transient 
error handling for the JMS trigger is configured to Suspend and retry later (non‐
transacted JMS trigger) or Suspend and recover (transacted JMS trigger), Integration 
Server suspends the trigger and schedules a system task to execute the trigger’s 
resource monitoring service (if one is specified). Integration Server enables the trigger 
and retries trigger execution when the resource monitoring service indicates that the 
resources used by the trigger are available. 
If a resource monitoring service is not specified, you will need to resume the trigger 
manually (via the Integration Server Administrator or the pub.trigger:enableJMSTriggers 
service). For more information about configuring a resource monitoring service, see 
Appendix B, “Building a Resource Monitoring Service”. 
If the document resolver service ends with an ISRuntimeException, and transient 
error handling for the JMS trigger is configured to Throw exception (non‐transacted JMS 
trigger) or Recover only (transacted JMS trigger), Integration Server assigns the 
document a status of In Doubt, acknowledges the document, and generates a JMS 
retrieval failure event. 
If the document resolver service ends with an exception other than an 
ISRuntimeException, Integration Server assigns the message a status of In Doubt, 
acknowledges the message, and generates a JMS retrieval failure event.
The watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the 
default) for Integration Server to generate JMS retrieval failure events. For more 
information about JMS retrieval failure events, see “Generating Events for JMS Retrieval 
Failure” on page 72.

Extenuating Circumstances for Exactly-Once Processing

Although Integration Server provides robust duplicate detection capabilities, activity 
outside of the scope or control of the Integration Server retrieving the message might 
cause a JMS trigger to process a message more than once. Alternatively, situations can 
occur where Integration Server might determine a message is a duplicate when it is 
actually a new message.
For example, in the following situations a trigger with exactly‐once processing configured 
might process a duplicate message.
If the client sends a message twice and assigns a different UUID each time, Integration 
Server does not detect the second message as a duplicate. Because the messages have 
different UUIDs, Integration Server processes both messages.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 97

 6. Exactly-Once Processing for JMS Triggers

If the document resolver service incorrectly determines the status of a message to be 
new (when it is, in fact, a duplicate), the server processes the message a second time.
If a client sends a message twice, and the second message is sent after Integration 
Server removes the expired message UUID entries from the document history table, 
Integration Server determines the second message is new and processes it. Because 
the second message arrives after the first message’s entries have been removed from 
the document history database, Integration Server does not detect the second message 
as a duplicate.
If the time drift between the computers hosting a cluster of Integration Servers is 
greater than the duplicate detection window for the trigger, one of the Integration 
Servers in the cluster might process a duplicate message. (The size of the duplicate 
detection window is determined by the History time to live property under Exactly Once.)
For example, suppose the duplicate detection window is 15 minutes and that the clock 
on the computer hosting one Integration Server in the cluster is 20 minutes ahead of 
the clocks on the computers hosting the other Integration Servers. A trigger on one of 
the Integration Servers with a slower clock processes a message successfully at 10:00 
GMT. The Integration Server adds two entries to the document history database. Both 
entries use the same time stamp and both entries expire at 10:15 GMT. However, the 
Integration Server with the faster clock is 20 minutes ahead of the others and might 
reap the entries from the document history database before one of the other 
Integration Servers in the cluster does. If the Integration Server with the faster clock 
removes the entries before 15 minutes have elapsed and a duplicate of the message 
arrives, the Integration Servers in the cluster will treat the message as a new message. 

Note: Time drift occurs when the computers that host the clustered servers gradually 
develop different date/time values. Even if the administrator synchronizes the 
computer date/time when configuring the cluster, the time maintained by each 
computer can gradually differ as time passes. To alleviate time drift, synchronize the 
cluster node times regularly.

In some circumstances Integration Server might not process a new, unique message 
because duplicate detection determines the message is duplicate. For example:
If the sending client assigns two different messages the same UUID, the Integration 
Server detects the second message as a duplicate and does not process it.
If the document resolver service incorrectly determines the status of a message to be 
duplicate (when it is, in fact, new), Integration Server discards the message without 
processing it.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 98

 6. Exactly-Once Processing for JMS Triggers

Important! In the above examples, Integration Server functions correctly when determining 
the message status. However, factors outside of the control of the Integration Server create 
situations in which duplicate messages are processed or new messages are marked as 
duplicates. The designers and developers of the solution need to make sure that clients 
properly send messages, exactly‐once properties are optimally configured, and that 
document resolver services correctly determine a message’s status. 

Exactly-Once Processing and Performance

Exactly‐once processing for a JMS trigger consumes server resources and can introduce 
latency into message processing by triggers. For example, when Integration Server 
maintains a history of persistent messages processed by a JMS trigger, each trigger service 
execution causes two inserts into the document history database. This requires Integration 
Server to obtain a connection from the JDBC pool, traverse the network to access the 
database, and then insert entries into the database. 
Additionally, when the delivery count cannot conclusively determine a message’s status, 
the server must obtain a database connection from the JDBC pool, traverse the network, 
and query the database to determine whether the trigger processed the message. 
If querying the document history database is inconclusive or if the server does not 
maintain a document history for the trigger, invocation of the document resolver service 
will also consume resources, including a server thread and memory. 
The more duplicate detection methods that are configured for a trigger, the higher the 
quality of service. However, each duplicate detection method can lead to a decrease in 
performance.
If a trigger does not need exactly‐once processing (for example, the trigger service simply 
requests or retrieves data), consider leaving exactly‐once processing disabled for the 
trigger. However, if you want to ensure exactly‐once processing, you must use a 
document history database or implement a custom solution using the document resolver 
service. 

Configuring Exactly-Once Processing

Configure exactly‐once processing for a JMS trigger when you want the trigger to process 
persistent messages once and only once. If it is acceptable for a trigger service to process 
duplicates of a message, you should not configure exactly‐once processing for the trigger. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 99

 6. Exactly-Once Processing for JMS Triggers

Considerations for Configuring Exactly-Once Processing

Keep the following points in mind when configuring exactly‐once processing:
Integration Server can perform exactly‐once processing for persistent messages only. 
The sending client must set the JMSDeliveryMode to persistent. 
The JMS trigger must specify CLIENT_ACKNOWLEDGE for the acknowledgement mode.

You do not need to configure all three methods of duplicate detection. However, if 
you want to ensure exactly‐once processing, you must use a document history 
database or implement a custom solution using the document resolver service. 
A document history database offers a simpler approach than building a custom 
solution and will typically catch all duplicate messages. There may be exceptions 
depending on your implementation. For more information about these exceptions, see 
“Extenuating Circumstances for Exactly‐Once Processing” on page 97. To minimize 
these exceptions, it is recommended that you use a history database and a document 
resolver service.
Stand‐alone Integration Servers cannot share a document history database. Only a 
cluster of Integration Servers can (and must) share a document history database. 
Make sure the duplicate detection window set by the History time to live property is 
long enough to catch duplicate messages but does not cause the document history 
database to consume too many server resources. If sending JMS clients reliably send 
messages once, you might use a smaller duplicate detection window. If the JMS clients 
are prone to sending duplicate messages, consider setting a longer duplicate detection 
window. 
If you intend to use a document history database as part of duplicate detection, you 
must first install the document history database component and associate it with a 
JDBC connection pool. For instructions, see the webMethods Installation Guide. 

Configuring Exactly-Once Processing for a JMS Trigger

To set up exactly‐once processing for a JMS trigger, you can configure up to three methods 
of duplicate detection: delivery count, document history database, and a document 
resolver service. 

To configure exactly-once processing for a JMS trigger

1 In the Navigation panel, open the JMS trigger for which you want to configure 
exactly‐once processing.
2 In the Properties panel, under Exactly Once, set the Detect duplicates property to True.
3 To use a document history database as part of duplicate detection, do the following:

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 100
 6. Exactly-Once Processing for JMS Triggers

a Set the Use history property to True.
b In the History time to live property, specify how long the document history database 
maintains an entry for a message processed by this trigger. This value determines 
the length of the duplicate detection window. 
4 To use a service that you create to resolve the status of In Doubt messages, specify that 
service in the Document resolver service property. 
5 On the File menu, click Save.

Disabling Exactly-Once Processing

If you later determine that exactly‐once processing is not necessary for a JMS trigger, you 
can disable it. 

To disable exactly-once processing for a trigger

1 In the Navigation panel, open the trigger for which you want to configure exactly‐
once processing.
2 In the Properties panel, under Exactly Once, set the Detect duplicates property to False.
Developer disables the remaining exactly‐once properties. 
3 On the File menu, click Save.

Building a Document Resolver Service

A document resolver service is a service that you create to perform duplicate detection. 
Integration Server uses the document resolver service as the final method of duplicate 
detection. 
The document resolver service must do the following:
Use the pub.jms:documentResolverSpec as the service signature. Integration Server passes 
the document resolver service values for each of the variables declared in the input 
signature. 
Return a status of New, In Doubt, or Duplicate. Integration Server uses the status to 
determine whether or not to process the message. 
Catch and handle any exceptions that might occur, including an ISRuntimeException. 
For information about how Integration Server proceeds with duplicate detection 
when an exception occurs, see “Document Resolver Service and Exceptions” on 
page 97. For information about building services that throw a retry exception, see the 
webMethods Developer User’s Guide. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 101
 6. Exactly-Once Processing for JMS Triggers

Determine how far message processing progressed. If necessary, the document 
resolver service can issue compensating transactions to reverse the effects of a 
partially completed transaction. 

Viewing Exactly-Once Processing Statistics

You can use Integration Server Administrator to view a history of the In Doubt or 
Duplicate messages received by JMS triggers. Integration Server Administrator displays 
the name, UUID (universally unique identifier), and status for the Duplicate or In Doubt 
messages received by triggers for which exactly‐once processing is configured.
Integration Server saves exactly‐once statistics in memory. When Integration Server 
restarts, the statistics will be removed from memory. 

To view exactly-once processing statistics

1 Start webMethods Integration Server and open the Integration Server Administrator.
2 Under the Settings menu in the navigation area, click Resources.
3 Click Exactly-Once Statistics.

To clear exactly-once processing statistics

1 Start webMethods Integration Server and open the Integration Server Administrator.
2 Under the Settings menu in the navigation area, click Resources.
3 Click Exactly-Once Statistics.
4 Click Clear All Duplicate or In Doubt Document Statistics.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 102
Chapter 7. Managing JMS Triggers

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Controlling Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Enabling, Disabling, and Suspending JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 103
 7. Managing JMS Triggers

Introduction
Integration Server Administrator provides controls for managing JMS triggers and the 
resources used by JMS triggers. Specifically, you can use the controls provided by 
Integration Server Administrator to:
Increase or decrease the maximum number of server threads used for JMS triggers.

Change the maximum execution threads for concurrent JMS triggers.

Enable, disable, or suspend one ore more JMS triggers. 
The following sections provide more information about managing JMS triggers.

Controlling Thread Usage for JMS Triggers

You can use Integration Server Administrator to limit the number of server threads that 
JMS triggers can use. By default, Integration Server can consume up to 100% of the server 
thread pool for JMS triggers. However, server resources also need to be available to 
perform other functions. 

Viewing Thread Usage for JMS Triggers

Integration Server Administrator displays the number of server threads currently used by 
each JMS trigger on Integration Server. 

To view thread usage for JMS triggers

1 Open the Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging.
3 Click JMS Trigger Management.
Under Individual JMS Trigger Controls, in the Current Threads column, Integration Server 
Administrator displays the number of server threads currently used to receive and 
process messages for each JMS trigger. The Current Threads column displays Not 
Connected if Integration Server is not connected to a JMS provider. 

Increasing or Decreasing Thread Usage for JMS Triggers

Integration Server provides controls that you can use to manage server thread usage by 
JMS triggers. You can use the controls to:
Set the percentage of the server thread pool that Integration Server can use for 
receiving and processing all JMS triggers. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 104
 7. Managing JMS Triggers

Reduce maximum execution threads by the same percentage across all concurrent 
JMS triggers. This also decreases the rate at which concurrent JMS triggers process 
messages. 

To increase or decrease thread usage for JMS triggers

1 Open the Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging.
3 Click JMS Trigger Management.
4 Click Edit JMS Global Trigger Controls.
5 In the Thread Pool Throttle field, type the maximum percentage of the server thread 
pool that can be used for JMS triggers. This includes threads used to retrieve messages 
from the JMS provider and threads used to process messages. You must enter a value 
greater than zero. 
6 In the Individual Trigger Processing Throttle field, select the value, as a percentage of the 
configured maximum execution threads value, at which you want to the server to 
function. Integration Server applies this percentage to the maximum execution 
threads value for all concurrent JMS triggers. 
This value applies to concurrent JMS triggers only. 
7 Click Save Changes.
Notes:
If the Thread Pool Throttle percentage does not evaluate to a whole number when 
applied to the size of the server thread pool, Integration Server rounds up or down to 
the nearest whole number. 
Serial JMS triggers always process one message at a time. For a serial trigger, 
Integration Server uses the same thread for receiving and processing a message. The 
Individual Trigger Processing Throttle does not affect serial JMS triggers. 
Concurrent JMS triggers use a pool of consumers to receive and process messages. 
Each consumer will use a thread from the server thread pool to receive and process a 
message. A concurrent JMS trigger dedicates an additional thread to managing the 
pool of consumers. For example, a concurrent JMS trigger configured to process up to 
10 messages at a time can use a maximum of 11 server threads. 
If the percentage by which you reduce concurrent JMS trigger execution threads does 
not resolve to a whole number for a JMS trigger, Integration Server rounds up or 
rounds down to the nearest whole number. However, if rounding down would set the 
value to 0, the Integration Server rounds up to 1. For example, if you reduce Individual
Trigger Processing Throttle to 10% of maximum, a concurrent JMS trigger with a 
maximum execution threads value of 12 would have an adjusted value of 1 
(Integration Server rounds 1.2 down to 1). A concurrent JMS trigger with a maximum 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 105
 7. Managing JMS Triggers

execution threads value of 4 would have an adjusted value of 1 (Integration Server 
rounds 0.4 up to 1).
When you reduce the Individual Trigger Processing Throttle and save your changes, 
Integration Server does not meet the adjusted maximum by terminating any threads 
currently executing concurrent JMS triggers. Integration Server allows server threads 
processing messages for concurrent JMS triggers to execute to completion. Integration 
Server waits until the number of threads executing for a concurrent JMS trigger is less 
than the adjusted maximum before dispatching another server thread for that JMS 
trigger. 

Enabling, Disabling, and Suspending JMS Triggers

You can manage JMS triggers and the amount of resources they consume by changing the 
state of a JMS trigger. A JMS trigger can have one of the following states:

Trigger State Description

Enabled The JMS trigger is running and connected to the JMS provider. 
Integration Server retrieves and processes messages for the JMS 
trigger. 
Disabled The JMS trigger is stopped. Integration Server neither retrieves nor 
processes messages for the JMS trigger.
Suspended The JMS trigger is running and connected to the JMS provider. 
Integration Server has stopped message retrieval, but continues 
processing any messages it has already retrieved.

Using the Integration Server Administrator, you can:
Enable, disable, or suspend all JMS triggers.

Enable, disable, or suspend specific JMS triggers.
You might want to change the state of all JMS triggers at once as a quick way of freeing up 
server resources. This can be especially helpful in a situation in which Integration Server 
is functioning under heavy load and additional resources are needed immediately.
You might want to change the state for a specific JMS trigger in the following situations:
When a back‐end system needs maintenance or is becoming unresponsive, you might 
want to suspend JMS triggers that interact with the back‐end system. When the back‐
end system becomes available, you can enable the JMS triggers. 
After suspending or disabling all JMS triggers, you might enable specific JMS triggers. 
For example, if the server is functioning under an unusually heavy load, you might 
first suspend all JMS triggers and then gradually enable JMS triggers, starting with 
the JMS triggers involved in key processes. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 106
 7. Managing JMS Triggers

After Integration Server suspends a serial JMS trigger automatically because a fatal 
error occurred during message processing. For information about configuring a JMS 
trigger for fatal error handling, see “Handling Fatal Errors for Non‐Transacted JMS 
Triggers” on page 65.
The following procedure explains how to use Integration Server Administrator to change 
the state of all or individual JMS triggers.

To enable, disable, or suspend JMS triggers

1 Open the Integration Server Administrator if it is not already open.
2 In the Settings menu of the Navigation panel, click Messaging.
3 Click JMS Trigger Management.
4 If you want to change the state of all JMS triggers, do the following:
a Under Individual JMS Trigger Controls, in the Enabled column, click edit all.
b On the Settings > Messaging > JMS Trigger Management > Edit State screen, in the New
State list, select the state that you want to apply to all JMS triggers.
5 If you want to change the state of a specific JMS trigger, do the following:
a Under Individual JMS Trigger Controls, in the row for the JMS trigger that you 
want to enable, disable, or suspend, click the text in the Enabled column
b On the Settings > Messaging > JMS Trigger Management > Edit State: triggerName screen, 
in the New State list, select the state that you want to apply to this JMS trigger.
6 Click Save Changes.
Notes:
If you want to disable a JMS trigger, first suspend the JMS trigger and wait for all the 
processing threads complete. Then, disable the JMS trigger. You can view the number 
of threads currently used by a JMS trigger on the Settings > Messaging > JMS Trigger
Management screen. 
When you disable a JMS trigger, Integration Server does the following:
If the JMS trigger is waiting before making a retry attempt, Integration Server 
interrupts processing for the JMS trigger.
If the JMS trigger is currently processing messages, Integration Server waits a 
specified amount of time before forcing the JMS trigger to stop processing 
messages. If it does not complete in the allotted time, Integration Server stops the 
message consumer used to receive messages for the JMS trigger and closes the 
JMS session. At this point the server thread for the JMS trigger continues to run to 
completion. However, the JMS trigger will not be able to acknowledge the 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 107
 7. Managing JMS Triggers

message when processing completes. If the delivery mode of the message is set to 
persistent, this can lead to duplicate messages.
The time Integration Server waits between the request to disable the JMS trigger 
and forcing the trigger to stop is specified by the 
watt.server.jms.trigger.stopRequestTimeout property.

Because administered objects, like destinations, are configured outside of Integration 
Server, disabling a JMS trigger has no impact on the subscription.
If a JMS trigger is processing messages at the time it is suspended, the JMS trigger will 
complete processing of those messages. The JMS trigger also acknowledges the 
messages to the JMS provider. 
You can use built‐in services to enable, disable, and suspend one or more triggers. For 
information about the pub.trigger:disableJMSTriggers, pub.trigger:enableJMSTriggers, and 
pub.trigger:suspendJMSTriggers services, see the webMethods Integration Server Built‐In 
Services Reference.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 108
Appendix A. JMS Server Configuration Parameters

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

watt.server.jms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 109
 A. JMS Server Configuration Parameters

Introduction
This appendix contains a description of the JMS‐related parameters you can specify in the 
server configuration file (server.cnf), which is located in the 
IntegrationServer_directory\config directory. Typically you will use the Settings > Extended
screen from the Integration Server Administrator to update this file, but there might be 
times when you need to edit the file directly using a text editor. If you edit the file directly, 
you should first shut down the Integration Server before updating the file. After you make 
the changes, restart the server.
The server uses default values for many of the parameters. If a parameter has a default, it 
is listed with the description of the parameter. Many of these parameters are set as you 
administer the webMethods Integration Server using the Integration Server 
Administrator.

watt.server.jms
watt.server.jms.connection.pingPeriod
Specifies how often, measured in seconds, Integration Server should ping the JMS 
provider. The ping serves as a keep alive request sent to the JMS provider. The default is 
300 seconds (5 minutes). 

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.connection.retryPeriod
Specifies the length of time, in seconds, that Integration Server waits between connection 
attempts when a connection to the JMS provider or JNDI provider fails. The default is 20 
seconds.

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.csq.batchProcessingSize
Specifies the maximum number of messages Integration Server retrieves from the client 
side queue and then sends to the JMS provider. Integration Server places sent messages in 
the client side queue when the connection to the JMS provider fails. Integration Server 
begins to drain the client side queue after the connection to the JMS provider becomes 
available. The default is 25.

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.debugTrace
Enables an extra level of verbose logging for JMS triggers that can be controlled globally 
or at the individual JMS trigger level. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 110
 A. JMS Server Configuration Parameters

To enable debugTrace logging for all JMS triggers, set the watt.server.jms.debugTrace 
property to true. For this setting to take effect, you need to disable and then enable all 
JMS triggers. For information about using Integration Server Administrator to enable 
and disable all JMS triggers, see “Enabling, Disabling, and Suspending JMS Triggers” 
on page 106.
To enable debugTrace logging for an specific JMS trigger, append the fully qualified 
JMS trigger name to the watt.server.jms.debugTrace property and set that property to 
true. For example, to enable debugTrace logging for the JMS trigger named 
myFolder:myJMSTrigger, enter the following on the Edit Extended Settings page:
watt.server.jms.debugTrace.myFolder:myJMSTrigger=true
For this setting to take effect, you need to disable and then enable the JMS trigger 
specified in the property. For information about using Integration Server 
Administrator to disable and enable an individual trigger, see “Enabling, Disabling, 
and Suspending JMS Triggers” on page 106.
watt.server.jms.trigger.maxDeliveryCount
Specifies the maximum number of times the JMS provider can deliver a message to 
Integration Server. The default is 100.

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.trigger.maxPrefetchSize
Specifies the maximum number of messages that the webMethods JMS API will retrieve 
and cache per request for a JMS trigger. Using pre‐fetch cache can speed up the retrieval of 
messages from the webMethods JMS Provider. Because messages will be placed in 
Integration Server memory, you may want to decrease this setting if you have JMS triggers 
receiving very large messages. Otherwise, memory issues can occur. This property only 
applies to JMS triggers receiving messages from the webMethods JMS Provider. The 
default is 10 messages. 
Integration Server checks this value when a JMS trigger starts. To apply a new value to all 
JMS triggers, use Integration Server Administrator to disable and then enable JMS 
triggers. For more information about enabling and disabling JMS triggers, see “Enabling, 
Disabling, and Suspending JMS Triggers” on page 106.
When working in a cluster of Integration Servers, the behavior controlled by this property 
might appear at first to be misleading. For example, suppose that you have a cluster of 
twoIntegration Serverss. Each Integration Server contains the same JMS trigger. Twenty 
messages are sent to a destination from which JMS trigger receives messages. It might be 
expected the JMS trigger on Integration Server 1 will receive the first message, the JMS 
trigger on Integration Server 1 will receive the second message, and so forth. However, 
what may happen is that the JMS trigger on Integration Server 1 will receive the first 10 
messages and the JMS trigger on Integration Server 2 will receive the second 10 messages. 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 111
 A. JMS Server Configuration Parameters

watt.server.jms.trigger.monitoringInterval
Specifies the interval, measured in seconds, at which Integration Serverexecutes resource 
monitoring services for JMS triggers. A resource monitoring service is a service that you 
create to check the availability of resources used by a JMS trigger service. After Integration 
Server suspends a JMS trigger because all retry attempts have failed, it schedules a system 
task to execute the resource monitoring service assigned to the JMS trigger. The default is 
60 seconds. Changes to this property take effect the next time Integration Server schedules 
a system task to execute a resource monitoring service for a JMS trigger. 
For more information about building resource monitoring services for JMS triggers, see 
Appendix B, “Building a Resource Monitoring Service”.
watt.server.jms.trigger.pooledConsumer.timeout
Specifies the length of time, in milliseconds, that a pooled consumer should remain active. 
Integration Server uses a pool of consumers to retrieve and process messages for 
concurrent JMS triggers. Each consumer in the pool encapsulates an actual 
javax.jms.MessageConsumer and javax.jms.Session. The default is 60,000 milliseconds (60 
seconds).

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.trigger.raiseEventOnException
Indicates whether Integration Server generates a JMS retrieval failure event when a JMS 
trigger experiences a fatal exception, such as a non‐transient error or a message that 
cannot be reprocessed, during message processing. Specify true if you want Integration 
Server to generate a JMS retrieval failure event. The default is true. 

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.trigger.raiseEventOnRetryFailure
Indicates that Integration Server generates a JMS retrieval failure event when a JMS 
trigger experiences a retry failure. A retry failure can occur when the JMS provider has 
reached the max delivery count for a message or when an ISRuntimeException is thrown 
and the JMS trigger is not configured to recover the message (for example, if retry failure 
handling for a non‐transacted JMS trigger is set to “Throw exception” instead of “Suspend 
and Retry Later”.) When set to true, Integration Server generates a JMS retrieval failure 
event for a JMS trigger when retry failure occurs. The default is true.

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.trigger.reuseSession
Indicates whether instances of a JMS trigger use the same session on Integration Server 
When this property is set to true, the JMS trigger uses a shared session. Each of the trigger 
services executed by the JMS trigger will use the same session ID. When this property is 
set to false, Integration Server uses a new session for each instance of a JMS trigger. 
Reusing sessions for a JMS trigger might improve performance. However, this property 

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 112
 A. JMS Server Configuration Parameters

does not work with all adapters. If you are working with an adapter, such as the SAP 
adapter, that requires the session ID to be unique, set this property to false. The default is 
false. 

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.trigger.stopRequestTimeout
Specifies the maximum amount of time, measured in seconds that Integration Server 
waits after a JMS trigger is disabled before forcing the JMS trigger to stop processing 
messages. The default is 3 seconds. 
You can disable a JMS trigger by invoking the pub.trigger:disableJMSTrigger service or by using 
or via the Settings > Messaging > JMS Trigger Management screens in Integration Server 
Administrator. For more information about disabling JMS triggers, see “Enabling, 
Disabling, and Suspending JMS Triggers” on page 106.
When you save a JMS trigger in Developer, Integration Serverstops and then restarts the 
trigger. In this situation, Integration Server waits 3 seconds before forcing the JMS trigger 
to stop processing messages. This value cannot be configured. 

Important! You must restart Integration Server for the new value to take effect.

watt.server.jms.wmjms.lms.readTimeout
Specifies the amount of time (measured in milliseconds) that Integration Server waits for 
the next portion of an input stream before throwing WmReadTimeoutException. The read 
timeout only applies after Integration Server retrieves the initial piece of the input stream. 
The default is 30000 milliseconds.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 113
 A. JMS Server Configuration Parameters

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 114
Appendix B. Building a Resource Monitoring Service

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 115
 B. Building a Resource Monitoring Service

Overview
A resource monitoring service is a service that you create to check the availability of 
resources used by a trigger. Integration Server schedules a system task to execute a 
resource monitoring service after it suspends a trigger. Specifically, Integration Server 
suspends a trigger and invokes the associated resource monitoring service when one of 
the following occurs:
During exactly‐once processing, the document resolver service ends because of an 
ISRuntimeException and the 
watt.server.trigger.preprocess.suspendAndRetryOnError property is set to 
true (the default).
A retry failure occurs for a non‐transacted trigger and the configured retry behavior is 
suspend and retry later. 
A transient error occurs for a transacted JMS trigger and the configured behavior 
when transaction roll back occurs is to suspend the JMS trigger and recover the 
message 
The same resource monitoring service can be used for multiple triggers. When the service 
indicates that resources are available, Integration Server resumes all the triggers that use 
the resource monitoring service. 

Service Requirements
A resource monitoring service must do the following:
Use the pub.trigger:resourceMonitoringSpec as the service signature. 

Check the availability of the resources used by the document resolver service and all 
the trigger services associated with a trigger. Keep in mind that each condition in a 
trigger can be associated with a different trigger service. However, you can only 
specify one resource monitoring service per trigger. 
Return a value of “true” or “false” for the isAvailable output parameter. The author of 
the resource monitoring service determines what criteria makes a resource available. 
Catch and handle any exceptions that might occur. If the resource monitoring service 
ends because of an exception, Integration Server logs the exception and continues as if 
the resource monitoring service returned a value of “false” for the isAvailable output 
parameter.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 116
Appendix C. Transaction Management

Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 117
 C. Transaction Management

Transaction Management Overview

This appendix provides an overview of transaction management, including transaction 
types and implicit vs. explicit transactions. It also describes how Integration Server 
supports the built‐in services used to manage explicit transactions. For descriptions of 
each of the specific built‐in transaction management services, see “Built‐In Transaction 
Management Services” on page 121.

Transactions
Integration Server considers a transaction to be one or more interactions with one or more 
resources that are treated as a single logical unit of work. The interactions within a 
transaction are either all committed or all rolled back. For example, if a transaction 
includes multiple database inserts, and one or more inserts fail, all inserts are rolled back.

Transaction Types
Integration Server supports the following kinds of transactions:
A local transaction (LOCAL_TRANSACTION) which is a transaction to a resource’s 
local transaction mechanism
An XAResource transaction (XA_TRANSACTION) which is a transaction to a 
resource’s XAResource transaction mechanism
Integration Server can automatically manage both kinds of transactions, without 
requiring the user to do anything. For more information about implicit transactions, see 
“Implicit and Explicit Transactions” on page 119.
However, there are cases where users need to explicitly control the transactional units of 
work. Examples of these cases are provided in “Implicit and Explicit Transactions” on 
page 119.
To support transactions, the Integration Server relies on a built‐in J2EE‐based transaction 
manager. The transaction manager is responsible for beginning and ending transactions, 
maintaining a transaction context, enlisting newly connected resources into existing 
transactions, and ensuring that local and XAResource transactions are not combined in 
illegal ways.
The transaction manager only manages operations performed by adapter services, a 
transacted JMS trigger, or a built‐in JMS service that uses a transacted JMS connection 
alias. 

Important! You cannot step or trace a flow that contains a transacted adapter service or a 
transacted JMS service.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 118
 C. Transaction Management

XA Transactions
If an XA transactional connection throws an exception during a service transaction and 
the exception results in an inconsistent state, you may need to resolve the transaction 
using the tools provided with the database.
For information about using the Integration Server to manage XA transactions, see the 
webMethods Integration Server Administrator’s Guide.

Implicit and Explicit Transactions

Implicit transactions are automatically handled by Integration Server transaction 
manager. When you define an explicit transaction, you define the start‐on‐completion 
boundaries of the transaction. As such, implicit and explicit transactions need to be 
created and managed differently.
The following sections describe implicit and explicit transactions and how to manage 
them.

Implicit Transactions
With implicit transactions, Integration Server automatically manages both local and 
XAResource transactions without requiring you to explicitly do anything. That is, the 
Integration Server starts and completes an implicit transaction with no additional service 
calls required by the user.
A transaction context, which the transaction manager uses to define a unit of work, starts 
when one of the following occurs:
An adapter service is encountered during flow service execution. The connection 
required by the adapter service is registered with the newly created context and used 
by the adapter service. If another adapter service is encountered, the transaction 
context is searched to see if the connection is already registered. If the connection is 
already registered, the adapter service uses this connection. If the connection is not 
registered, a new connection instance is retrieved and registered with the transaction.
 Integration Server uses a transacted JMS connection alias to receive messages from 
the JMS provider for a JMS trigger. A JMS connection alias is considered to be 
transacted when it has a transaction type of XA TRANSACTION or LOCAL 
TRANSACTION. 
A built‐in JMS service that uses a transacted JMS connection alias to connect to the 
JMS provider is encountered during flow service execution. 
Note that if the top‐level flow service invokes another flow, services in the child flow use 
the same transaction context.
When the top‐level flow service completes, the transaction is completed and is either 
committed or rolled back, depending on the status (success or failure) of the top‐level flow 
service or the JMS trigger service.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 119
 C. Transaction Management

A single transaction context can contain any number of XA_TRANSACTION connections 
but no more than one LOCAL_TRANSACTION connection. 
For more information about designing and using flows, see the webMethods Developer 
User’s Guide.

Explicit Transactions
You use explicit transactions when you need to explicitly control the transactional units of 
work. To do this, you use additional services, known as built‐in services, in your flow.
A transaction context starts when the pub.art.transaction:startTransaction service is executed. 
The transaction context is completed when either the pub.art.transaction:commitTransaction or 
pub.art.transaction:rollbackTransaction service is executed. As with implicit transactions, a single 
transaction context can contain any number of XA_TRANSACTION connections but no 
more than one LOCAL_TRANSACTION connection. 

Note: With explicit transactions, you must be sure to call either a 
pub.art.transaction:commitTransaction or pub.art.transaction:rollbackTransaction for each 
pub.art.transaction:startTransaction; otherwise you will have dangling transactions that will 
require you to reboot the Integration Server. You must also ensure that the 
startTransaction is outside the SEQUENCE.

A new explicit transaction context can be started within a transaction context, provided 
that you ensure that the transactions within the transaction context are completed in the 
reverse order they were started—that is, the last transaction to start should be the first 
transaction to complete, and so forth.
For example, consider the following is a valid construct:
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction

The following example shows an invalid construct:
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction

Note: You can use the pub.flow:getLastError service in the SEQUENCE, to retrieve the error 
information when a sequence fails. For more information on using the pub.flow:getLastError 
service, see the webMethods Developer User’s Guide.

For more information about designing and using flows, see the webMethods Developer 
User’s Guide.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 120
 C. Transaction Management

Built-In Transaction Management Services

The following table identifies each of the built‐in services you can use for transaction 
management.

Service Description
pub.art.transaction:commitTransaction Commits an explicit transaction. It must be used 
in conjunction with the 
pub.art.transaction:startTransaction service. If it does 
not have a corresponding 
pub.art.transaction:startTransaction service, your flow 
service will receive a run time error
pub.art.transaction:rollbackTransaction Rolls back an explicit transaction. It must be used 
in conjunction with the 
pub.art.transaction:startTransaction service. If it does 
not have a corresponding 
pub.art.transaction:startTransaction service, your flow 
service will receive a run time error.
pub.art.transaction:setTransactionTimeout Manually sets a transaction timeout interval for 
implicit and explicit transactions. When you use 
this service, you are temporarily overriding the 
Integration Server transaction timeout interval. 
pub.art.transaction:startTransaction Starts an explicit transaction. It must be used in 
conjunction with either a 
pub.art.transaction:commitTransaction service or 
pub.art.transaction:rollbackTransaction service. If it does 
not have a corresponding 
pub.art.transaction:commitTransaction service or 
pub.art.transaction:rollbackTransaction service, your 
flow service will receive a run time error.

For more information about the transaction management services, including detailed 
descriptions of the service signatures, see the webMethods Integration Server Built‐In 
Services Reference.

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 121
 C. Transaction Management

webMethods Integration Server JMS Client Developer’s Guide Version 7.1 122