webMethods Developer User's Guide - Software AG Documentation

Title Page 

webMethods, Inc. 

South Tower 

3877 Fairfax Ridge Road 

Fairfax, VA 22030 

USA 

703.460.2500 

http://www.webmethods.com 

webMethods Developer User’s Guide 

VERSION 6.5, SERVICE PACK 3 

DECEMBER 2006

Copyright 

& Document 

ID 

B2B Integration Server, Business Process Integration, Cerebra, Get There Faster, Glue, Glueprints, Glueware, Guided SOA Governance, Infravio X-Broker, 

Infravio X-Registry, Infravio, My webMethods Server, My webMethods, Process Improvement Lifecycle, Process Improvement Lifecycle Methodology, 

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 SOA Governance, webMethods SOA Management, webMethods Task Engine, 

webMethods Trading Networks, webMethods Workflow, and webMethods are either registered trademarks or trademarks of webMethods, Inc. in the United 

States and/or other countries. 

Acrobat and Adobe are registered trademarks, and Reader is a trademark of Adobe Systems Incorporated. Amdocs is a registered trademark, and ClarifyCRM 

is a trademark 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. ChemeStandards and CIDX are trademarks of Chemical Industry Data Exchange. 

Unicenter is a registered trademark of Computer Associates International, Inc. PopChart is a registered trademark of CORDA Technologies, Inc. Kenan and 

Arbor are registered trademarks of CSG Systems, Inc. Data Connection and SNAP-IX are registered trademarks of Data Connection Corporation. DataDirect, 

DataDirect Connect, and SequeLink are registered trademarks of DataDirect Technologies. D&B and D-U-N-S are registered trademarks of Dun & Bradstreet 

Corporation. 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, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, 

RACF, RS/6000, SQL/400, S/390, System/390, VTAM, z/OS, and WebSphere 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. JBoss is a registered trademark, and JBoss Group is a trademark of Jboss, Inc. 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, Windows, and Windows NT are registered trademarks; and Windows Server is a trademark of 

Microsoft Corporation. Six Sigma is a registered trademark of Motorola, Inc. Firefox is a registered trademark, and Mozilla is a trademark of the Mozilla 

Foundation. MySQL is a registered trademark of MySQL AB. nCipher is a trademark of nCipher Corporation Ltd. Teradata is a registered trademark of NCR 

International, Inc. 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 PeopleSoft Pure Internet Architecture and WorldSoftware are trademarks of Oracle Corporation. Infranet and Portal 

are trademarks of Portal Software, Inc. Red Hat is a registered trademark 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. SWIFT and SWIFTNet are registered trademarks of Society for Worldwide Interbank 

Financial Telecommunication SCRL. SPARC and SPARCStation are registered trademarks of SPARC International, Inc. SSA is a registered trademark, and 

Baan and SSA Global are trademarks 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, SOAP with Attachments API for Java, JavaServer Pages, 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. 

All other marks are the property of their respective owners. 

Copyright © 2006 by webMethods, Inc. All rights reserved, including the right of reproduction in whole or in part in any form. 

Document ID: DEV-UG-65SP3-20061222

Contents 

Contents 

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Chapter 1. Getting Started with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

The Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

Navigation Panel Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Refreshing the Contents of the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

The Servicenet Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Servicenet Tab Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

The Recent Elements Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

The Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

The Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Moving Between Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Performing Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 

Resizing Areas in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Hiding and Showing Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Dragging Movable Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 

Switching Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 

Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

Restoring a Session on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

Notification of Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Chapter 2. Managing Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

About Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

Package Names and Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

webMethods Developer User’s Guide Version 6.5, Service Pack 3 � � � 3

Contents 

Guidelines for Naming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

Editing Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 

Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

Moving and Copying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

Copying Elements Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 

Moving and Copying Adapter Notifications and Related Elements . . . . . . . . . . . . . . . 53 

Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Finding Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Finding Fields in Editor Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

Locating Invoked Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

Finding Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

Finding References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 

Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

Clearing the Developer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

Chapter 3. Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 

What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 

Guidelines for Naming Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 

Viewing Details for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

Optimizing Lock Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

Copying a Package to Another Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 

Documenting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 

Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Exporting a Package or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

Assigning a Version Number to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Viewing the Patch History for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Identifying Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 

Removing Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 

Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 


Contents 

What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 

What Is a Shutdown Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

Guidelines for Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . 89 

Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Removing Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

Chapter 4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

How Do I Know Who Has an Element Locked? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

When Do I Lock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

When Do I Unlock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 

Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 

System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 

Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 

Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

Unlocking Elements Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

Unlocking an Element Using the Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . 101 

Unlocking a System Locked Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 

Viewing an Element’s Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 

Automatically Unlocking Elements After Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Lock/Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 

Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 

Chapter 5. Assigning and Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 


What Is an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 

What Happens When a Client Runs a Service with ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 

Am I Required to Use ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 

How Do I Create an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 

Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 

The Permissions Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 


Contents 

ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 

Default ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 

ACLs and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 

ACLs and Testing/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 

ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 

Chapter 6. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 


What Is a Flow Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 

What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 

What Is the Pipeline? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 

What Are Input and Output Parameters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 

Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Package and Folder Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Using the Default Logic Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 

Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

Specifying Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Specifying Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

Completing the Input/Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 

Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 

Maintaining the State of a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 

Configuring a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

Types of Services to Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

Services Suited for Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Services that You Should Not Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Controlling a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Specifying the Duration of a Cached Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 

Using the Prefetch Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 

Specifying the Execution Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 

Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 

Assigning Universal Names to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 

Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 


Contents 

Enabling Auditing for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 

Specifying When Audit Data Is Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 

Including the Pipeline in the Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 

When Is a Copy of the Input Pipeline Saved in the Audit Log? . . . . . . . . . . . . . . . . . . . . . . 151 

Service Auditing Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 

Error Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 

Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 

Auditing for Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Auditing Long-Running Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Setting Auditing Options for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Audit Level Settings in Earlier Versions of Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 

Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 

Chapter 7. Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 

What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 

Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 

Changing the Position of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Changing the Level of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Setting the Properties of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 

The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 

Specifying the Service Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 

Invoking a Built-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 

Invoking a Service on Another webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 166 

Building an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 

The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 

Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

Specifying the Switch Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 

Specifying the Label Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 

Branching on an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 

Branching on Null and Empty Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 

Specifying a Default Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 

Using SEQUENCE as the Target of a BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 

Building a BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 

The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

Specifying the REPEAT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 

Setting the REPEAT Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 

When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 

Using REPEAT to Retry a Failed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 

Using REPEAT to Retry a Successful Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 

The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 

Using SEQUENCE to Specify an Exit Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 


Contents 

The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 

Specifying the Input Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 

Collecting Output from a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 

Building a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 

The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 

The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

Chapter 8. Mapping Data in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 

What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 

What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 

Pipeline Tab for an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 

Pipeline Tab for a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 

Pipeline Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 

Printing the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 

Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 

Linking Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 

What Happens When Integration Server Executes a Link Between Variables? . . . . . . . . . 206 

Linking to Document and Document List Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 

Linking Variables of Different Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 

Examples of Structural Transformations on the Pipeline Tab . . . . . . . . . . . . . . . . . . . 210 

Converting a String List to a Document List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 

Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 

Guidelines for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 

Deleting Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Applying Conditions to Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Linking Multiple Source Variables to a Target Variable . . . . . . . . . . . . . . . . . . . . . . . . 215 

Assigning Values to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

Assigning a Default Value to a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 

Initializing Variables in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Referencing Other Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Setting a Value for a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Copying Set Values Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 

Dropping Variables from the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 

Adding Variables with the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 

What Are Transformers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 

Using Built-in Services as Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 

Inserting a Transformer into a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 

Linking Variables to a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 

Transformer Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 

Transformers and Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 


Contents 

What Is Dimensionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 

Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Validating Input and Output for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Copying Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 

Expanding Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 

Renaming Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 

Debugging Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 

Chapter 9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . 233 

Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

What Does an IS Schema Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

Schema Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 

Schema Details Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 

Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Creating IS Schemas from XML Schemas that Reference Other Schemas . . . . . . . . . . . . 241 

Editing a Simple Type in an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Setting Constraining Facet Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 

Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 

Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . . . . . . . . . . 246 

Creating an IS Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . . . . . . . . 248 

The Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 

Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 

Editing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 

Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 

Printing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 

Using an IS Document Type to Specify Service Input or Output Parameters . . . . . . . . . . . . . . . 253 

Using an IS Document Type to Build a Document Reference or Document Reference List Field 254 

Specifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 

Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 

Chapter 10. Performing Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 

What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

What Is Data Validated Against? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Considerations for Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 

Customizing a String Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 

Viewing the Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 

Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 

Specifying Input/Output Validation via the Input/Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 


Contents 

Specifying Input/Output Validation via the INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 

Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 

Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 

Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 

Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 

Running Out of Memory During Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 

Chapter 11. Testing and Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 

Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 

Entering Input for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 

Saving Input Values to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 

Loading Input Values from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 

Viewing the Results of the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 

Copying Variables from the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 

Run-Time Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 

The Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 

The Pipeline Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 

Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 

Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 

Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 

Entering Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 

Combining the Step and Trace Commands in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 

Resetting Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 

Using the Trace Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 

Tracing into a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 

Using the Step Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 

Stepping though a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

Using the Step Tools with a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 

What Happens When a Breakpoint Is Encountered? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 

Setting Breakpoints on Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 

Viewing a List of Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

Disabling Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

Disabling Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 

Disabling a Condition Placed on a Link Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 

Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 


Contents 

Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 

Saving the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 

Saving the Contents of the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 

Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 

Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 

Loading a Saved Pipeline into the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 

Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 

Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 

Using the Server’s Debug Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 

The Contents of the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 

Server Debug Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 

Writing Information to the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 

Writing an Arbitrary Message to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 

Dumping the Pipeline to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 

Chapter 12. Building Coded Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 


The IData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 

Services Take IData Objects as Input and Return IData as Output . . . . . . . . . . . . . . . . . . 316 

Getting and Setting Elements in an IData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 

Creating IData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 

Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 

Using the Developer IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 

The Java Service Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 

The Shared Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 

Creating a Java Service with Developer’s IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 

Generating Java Code from Service Input and Output Parameters . . . . . . . . . . . . . . . . . . 325 

Setting Run-Time Options for a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 

Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 

The Namespace Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 

The Source Code Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 

Writing the Source Code for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 

Using the webMethods API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 

The Basic Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 

Commenting Code for the webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . 329 

Using the jcode Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 

Make Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 

Fragment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 

Composite Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 


Contents 

Other jcode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 

Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 

Generating Files for a C/C++ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 

The Java Code for a C Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 

Building the C/C++ Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 

Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

Creating the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

Invoking the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 

Writing and Invoking a Visual Basic Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 

Compiling a Visual Basic Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 

Invoking a Visual Basic Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 

Invoking a VB Service Using Late Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 

Invoking a VB Service Using Early Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 

Chapter 13. Creating Client Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 


Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Third-Party Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 

Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 

Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 


Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 


General Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 

Files for the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 

Files Containing the Code that Invokes the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 

File Containing the Code that Interacts with webMethods Integration Server . . . . . . . . . . . 354 

Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 

Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 


Contents 

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 


Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 

Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 

Invoking Services with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 

Using the HTTP GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 

Using the HTTP POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 

Input to the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 

Output from the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 

Chapter 14. Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 

The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 

What Are Event Handlers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

What Happens When an Event Occurs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 

Subscribing to an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 

Creating Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 

Creating Event Filters for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 

Viewing and Editing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 

Suspending Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 

Deleting an Event Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 

Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 

Sample Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 

Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 

Building Handlers for Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 

Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 

Building Handlers for Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 

Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 

Building Handlers for Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 

Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 

Guaranteed Delivery Events and Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 

Building Handlers for Guaranteed Delivery Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 

Building Handlers for Guaranteed Delivery End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 

Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 

Building Handlers for Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

Building Handlers for Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 

Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 

Building Handlers for Session Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 


Contents 

Building Handlers for Session End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 

Building Handlers for Session Expire Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

Building Handlers for Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 

Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 

Building Handlers for Transaction Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 

Building Handlers for Transaction End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 

Chapter 15. Building Services that Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

Adapter Services and Retry Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 

How to Build a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 

Example—Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . 394 

Appendix A. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 

BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 

Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 

Branching on Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 

Conditions that Will Cause a BRANCH Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 

EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

Conditions that Will Cause an INVOKE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 

LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 

Conditions that Will Cause a LOOP Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

Example of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 

REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 

When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 

Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 

SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 

Conditions that Will Cause the SEQUENCE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 


Contents 

Appendix B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 

What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 

Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 

Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 

Appendix C. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 

Java Classes for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 

How webMethods Developer Supports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 

Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

Appendix D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 

Comparing Java Objects to Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 

Checking for Variable Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 

Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 

Standard Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 

Lexical Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 

Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 

Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

Addressing Variables that Contain Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 

Typing Special Characters in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 

Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 

Appendix E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 

jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 

jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 

Sample Code—IData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 

Appendix F. Validation Content Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 

Appendix G. Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 

Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 

Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 

IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 


Contents 

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 


About This Guide 

Document Conventions 


This guide describes how to create services using webMethods Developer. It contains 

information for developers who want to build services using the webMethods flow 

language or a programming language such as Java, C/C++, or Visual Basic. 

To use this guide effectively, you should know how to program in Java, C/C++, and/or 

Visual Basic if you will be creating services in those languages. 

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 

font 

Identifies characters and values that you must type exactly or 

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 components: 

� Troubleshooting Information. webMethods provides troubleshooting information for 

many webMethods components in the webMethods Knowledge Base. 

� Documentation Feedback. To provide documentation feedback to webMethods, go to the 

Documentation Feedback Form on the webMethods Bookshelf. 

� Additional Documentation. All webMethods documentation is available on the 

webMethods Bookshelf. 


Chapter 1. Getting Started with Developer 

� What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

� Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

� Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

� What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

� Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

� Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

� Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

� Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 


What Is Developer? 

1. Getting Started with Developer 

webMethods Developer is a graphical development tool that you use to build, edit, and 

test integration logic. It provides an integrated development environment in which you 

can develop the logic and supporting objects (referred to as elements) of an integration 

solution. It also provides tools for testing and debugging the solutions you create. 

Developer lets you rapidly construct integration logic with an easy-to-use implementation 

language called the webMethods flow language. Flow language provides a set of simple but 

powerful constructs that you use to specify a sequence of actions (steps) that the 

Integration Server will execute at run time. Developer also has extensive data 

transformation and mapping capabilities that allow you to quickly drag-and-drop data 

fields from one step to the next. 

Besides providing tools for constructing flow services, Developer provides additional 

editors and tools for creating various elements that support the execution of an 

integration solution. For example, you use Developer to create the document types and 

schemas used for data validation and to define triggers that launch the execution of 

services when certain documents are published. 

Developer enables you to lock an element you are working with. When you lock an 

element, the element is read-only to all other users on the Integration Server. Another user 

cannot edit the element until you unlock it. Developer can also be configured to interact 

with a third-part version control system (VCS) repository; in this case, elements are locked 

and unlocked as you check them out of and in to the VCS repository. 

All references in this guide to locking refer to local locking on the Integration Server. For 

specific information about local file locking, see Chapter 4, “Locking and Unlocking 

Elements”. For information on how to implement file locking with the Version Control 

System Integration feature for Developer, see the webMethods Version Control System 

Integration Feature Developer’s Guide in the ..\webMethods6\Developer\doc\guides 

directory of your webMethods installation. 

Before You Use Developer 

Developer builds and edits services directly on a server. To use Developer you must: 

� Have access to a webMethods Integration Server on which you can build and test 

services. 

� Have a user account on that webMethods Integration Server. 

� Belong to a group that is a member of the “Developers” ACL (access control list) on 

that webMethods Integration Server. 

If you do not have access to a webMethods Integration Server or you do not have an 

appropriate user account or access rights, see your server administrator. 


Starting Developer 


Use the following procedure to start Developer on your workstation. Before you start 

Developer keep the following in mind: 

� Make sure that the Integration Server with which you want to use Developer is 

running. You cannot work with Developer if the server is not running. 

� If you are starting Developer for the first time on a UNIX system, verify that the 

DEVELOPER_DIR and JAVA_DIR settings in developer.sh specify the paths where 

Developer (DEVELOPER_DIR) and Java Runtime Environment (JAVA_DIR) reside. If 

these settings are not correct, update them before starting Developer. 

Important! You can only connect webMethods Developer version 6.5 to a webMethods 

Integration Server version 6.1 or version 6.5. 

To start Developer 

1 Depending on which operating system is running on your workstation, do the 

following: 

If you are running... Do this... 

Windows a On the Start menu, click Programs, and then click 

webMethods. 

b Click webMethods Developer. 

UNIX a Navigate to the directory where you installed 

Developer. 

Specify the name and 

port assignment of a 

server... 

...and enter a user 

account that has 

developer privileges. 

b Run bin/developer.sh. 


2 In the Open Session dialog box, complete the following: 

In this field... Specify... 

3 Click OK. 


Server type The registered type for the server on which you want to open a 

session. The default type is Integration Server. 

Server The name and port assignment of the webMethods Integration 

Server in ServerName:PortNum format. 

Example rubicon:5555 

Note: Servers to which you have successfully logged on in the 

past are listed in the Server list. You can select a server from this 

list or type its name and port number. 

Username The name of a valid user account on this server. (The user name 

must be a member of a group belonging to the Developers 

ACL.) 

Use the exact combination of upper- and lower-case characters 

with which it was originally defined. IS user names are case 

sensitive. 

Note: The server is installed with a default user account called 

“Developer” that has developer privileges. 

Password The password for the user account in Username. Use the exact 

combination of upper- and lower-case characters with which it 

was originally defined. IS passwords are case sensitive. 

Uses secure 

connection 

Note: The default password for the Developer user account is 

isdev. 

Whether the session will be opened through HTTP or HTTPS. 

If you want to open an HTTPS session on the selected server 

using the Secure Socket Layer (SSL), select this check box. If 

you want to open an HTTP session on the server, clear this 

check box. 

Uses proxy Whether the session will be opened through the default proxy 

server. If you want to open a session on the selected server 

using your proxy server, select this check box. 



Tip! When you run Developer from the command line, Developer writes messages to the 

console. The amount and type of information that is written is determined by the debug 

level under which Developer is operating. The default debug level is 4. If you want more 

detail written to the console, set the debug level to 10. You can change the debug level by 

editing the ini.cnf file located in webMethods6\Developer\config. 

Note: When you start Developer, it verifies that the other webMethods components 

support the same locale as Developer. If the locale of an add-in component is not 

supported by the Developer locale, Developer displays a message in the console warning 

you of the locale mismatch. For example, if you start Developer in an English locale with a 

localized Japanese add-in component, Developer displays the following message in the 

console: 

Warning: The following plug-ins are running localized versions even though 

Developer is not: ComponentName; VersionNumber. 

Developer will display some text in English and the component’s text in Japanese. 

What Does the Developer Window Contain? 

The Developer window is divided into the following areas: 

� Navigation panel. You use the Navigation panel to select, lock, copy, move, delete, or 

rename elements. If the VCS Integration feature is enabled, you can check elements in 

to and out of a VCS repository. For more information about this panel, see “The 

Navigation Panel” on page 24. 

� Servicenet tab. You use the Servicenet tab to connect and disconnect Servicenet 

sessions, and to display, filter, and register Web services. For more information about 

this panel, see “The Servicenet Tab” on page 28. 

� Recent Elements tab. You use the Recent Elements tab to quickly access elements you 

have recently viewed. For more information about this panel, see “The Recent 

Elements Tab” on page 29. 

� Editor. You use the editor to examine and edit an element you opened from the 

Navigation panel or Recent Elements tab. For more information about the editor, see 

“The Editor” on page 30. 

� Properties panel. You use the Properties panel to view and edit the properties for an 

item. For more information about this panel, see “The Properties Panel” on page 31. 

� Results panel. You use the Results panel to view the result of a service’s execution, to 

view the variables that a service adds to the pipeline, and to view the contents of those 

variables. For more information about this panel, see “The Results Panel” on page 33. 


The Navigation Panel 

displays the contents of 

servers, packages, and 

folders. 

The Editor displays the 

controls you use to examine 

and edit an element you 

have opened from the 

Navigation panel or Recent 

Elements tab. 

The Servicenet tab displays 

available Web services, if a 

Servicenet session is open. 

The Recent Elements Tab 

displays the elements you 

viewed most recently. 

Developer main window 

The Navigation Panel 


The Properties Panel 

displays the properties 

for an item. 

The Results Panel 

displays the results of a 

service’s execution. 

The Navigation panel displays the contents of packages on the webMethods Integration 

Servers on which you have an open session. You use the Navigation panel to perform 

tasks such as creating, opening, locking, copying, moving, renaming, and deleting 

elements. If the VCS Integration feature is enabled, you can check elements in to and out 

of a VCS repository. 

Elements in the Navigation panel are shown in a hierarchical structure where the server is 

the topmost element in the hierarchy. Packages on the server contain one or more folders, 

which contain other elements that you can create and edit using Developer (for example, 

services, specifications, and IS document types). 

For more information about the tasks you can perform on elements in the Navigation 

panel, see Chapter 2, “Managing Elements in the Navigation Panel” and Chapter 3, 

“Working with Packages”. 

For information on how to implement file locking with the Version Control System 

Integration feature for Developer, see the webMethods Version Control System Integration 

Feature Developer’s Guide in the ..\webMethods6\Developer\doc\guides directory of your 

webMethods installation. 


Navigation Panel Icons 


Each item in the Navigation panel contains an icon that denotes the item’s type. The 

following table describes what each icon represents. 

This icon... Represents... 

A server. You can have multiple server contexts displayed in Developer. 

The active server context is the one that is highlighted in the Navigation 

panel. To display the contents of the server, click the symbol next to its 

name. 

A package. A package contains a set of services and related files, such as 

specifications, IS document types, and output templates. To display the 

contents of a package, click next to its name. 

A folder. A folder contains related services and optional folders (called 

subfolders). To display the contents of a folder, click next to its name. 

A flow service. A flow service is a service written in the webMethods flow 

language. 

A Web service connector. A Web service connector is a flow service that 

invokes a Web service located on a remote server. Developer uses a 

WSDL document to automatically generate a Web service connector. 

A Java service. A Java service is a service written in Java. 

A C service. A C service is a service written in C/C++. 

A specification. A specification is a formal description of a service’s inputs 

and outputs. 

A trigger. A trigger associates one or more publishable document types 

with one or more services. At run time, when the Integration Server 

receives a document that satisfies the conditions of the trigger, the 

Integration Server executes/invokes the associated services. For more 

information about creating triggers, see the Publish-Subscribe Developer’s 

Guide. 

An IS document type. An IS document type contains a set of fields used to 

define the structure and type of data in a document. 

A publishable document type. A publishable document type is an IS 

document type with specific publishing properties. Instances of 

publishable document types can be published and subscribed to. 

Publishable document types can be used anywhere an IS document type 

is needed. 




A publishable document type for an adapter notification. An adapter 

notification can have an associated publishable document type that the 

adapter uses to send the notification data to an Integration Server or a 

Broker. 

An IS schema. An IS schema is the blueprint or model document against 

which you validate an XML document. The schema defines what can and 

cannot be contained in the XML documents it validates. 

An adapter notification. An adapter notification enables an adapter to 

receive event data from the adapter’s resource. There are two types of 

adapter notifications: 

� Polling notifications, which poll the resource for events that occur on 

the resource. 

� Listener notifications, which work with listeners to detect and 

process events that occur on the adapter resource. 

For information about creating an adapter notification, refer to the 

documentation provided with the adapter. 

An adapter service. An adapter service connects to an adapter’s resource 

and initiates an operation on the resource. Adapter services are created 

using service templates included with the adapter. For information about 

creating adapter services, refer to the documentation provided with the 

adapter. 

A listener. A listener is an object that connects to an adapter resource and 

waits for the resource to deliver data when an event occurs on the 

resource. Listeners work with listener notifications to detect and process 

event data on the adapter resource. 

For information about creating a listener, refer to the documentation 

provided with the adapter. 

A connection. A connection is an object that contains parameters that 

adapter notifications and listeners use to connect to a resource. For 

information about creating a connection, refer to the documentation 

provided with the adapter. 

A flat file dictionary. A flat file dictionary contains record definitions, field 

definitions, and composite definitions that can be used in multiple flat 

file schemas. For more information about creating a flat file dictionary, 

see the Flat File Schema Developer’s Guide. 



Refreshing the Contents of the Navigation Panel 


A flat file schema. A flat file schema is the blueprint that contains the 

instructions for parsing or creating the records in a flat file, as well as the 

constraints to which an inbound flat file document should conform to be 

considered valid. Using flat file schemas, you can translate documents 

into and from flat file formats. For more information about creating a flat 

file schema, see the Flat File Schema Developer’s Guide. 

An XSLT service. An XSLT service converts XML data into other XML 

formats or into HTML, using rules defined in an associated XSLT 

stylesheet. For more information about creating XSLT services, see the 

XSLT Services Developer’s Guide. 

Servicenet. Developer displays all of the Web services registered in the 

Servicenet below the Servicenet name. Developer displays the subnet 

locator port or the WAN locator URL for the Servicenet to which you are 

connected. 

A Web service. A Web service is a service that uses specific XML- based 

protocols and interface descriptions to communicate. 

A .NET service. A .NET service is a service that calls methods imported 

from .NET assemblies (using the webMethods for Microsoft Plug-in). 

Once a .NET service exists within Developer, it can become part of a flow 

just like any other service. For more information about using the 

Microsoft .NET application platform with webMethods components, see 

the webMethods for Microsoft Package Installation and User’s Guide. 

An Unknown Node. The webMethods component used to create/develop 

the element is not installed on the client machine. 

An Unknown Service. The webMethods component used to create this 

service is not installed on the client machine. 

Note: Other installed webMethods components might add elements to the Navigation 

panel that are not described in the preceding table. For information about these elements, 

refer to the documentation provided with these installed components. 

The Navigation panel on your screen is not dynamically updated when other users lock, 

unlock, add, delete, or rename elements on a server. To refresh the Navigation panel to 

reflect any changes made to the contents of the servers you are working with, use the 

Session�Refresh command. 


The Servicenet Tab 


Note: Refreshing the session is different from restoring a session. Restoring a session 

allows you to save changes to an element you were working with when the Integration 

Server shuts down unexpectedly. For more information about restoring sessions, see 

“Restoring a Session on a Server” on page 38. 

Use the Servicenet tab to connect and disconnect Servicenet sessions. Once you have 

opened a Servicenet session, you can display, filter, and register Web services. Within the 

Servicenet tab, Web services are sorted in alphabetical order. Simply select a Web service 

to view more information about the service. For more information about using Servicenet 

with Developer, see the Web Services Developer’s Guide. 

Note: When you select a Web service in the Servicenet tab, the editor (the middle area of 

the Developer window between the Navigation panel and the Properties panel) does not 

change. This is because Web service details and logic cannot be modified using Developer. 

Servicenet Tab Icons 

The following buttons on the Servicenet tab toolbar are shortcuts to frequently-used 

commands. 

Use this 

button... To... 

Connect to a Servicenet session while working in Developer. 

Equivalent to Session�Open Servicenet. 

Disconnect from a Servicenet session while working in Developer. 

Equivalent to Session�Close Servicenet. 

Refresh the display of Web services. Equivalent to Session�Refresh 

Servicenet. 

Create an expression that filters the contents of the Servicenet tab 

based on the value of a Web service property. Equivalent to 

Session�Set Servicenet Filter. 

Remove the filter from the contents of the Servicenet tab and 

display all the registered Web services. Equivalent to 

Session�Clear Servicenet Filter. 



The Servicenet tab also contains icons to represent the Servicenet and the Web services 

that are registered within Servicenet. The following table identifies these icons. 


Servicenet. Developer displays all of the Web services registered in 

the Servicenet below the Servicenet name. Developer displays the 

subnet locator port or the WAN locator URL for the Servicenet to 

which you are connected. 

A Web service. A Web service is a service that uses specific XMLbased 

protocols and interface descriptions to communicate. 

The Recent Elements Tab 

The Recent Elements tab lists the last 30 elements you viewed in the editor. Developer 

adds an element to this panel when you close the element. You can use this panel to 

quickly open elements that you have recently viewed and closed. 

Tip! To view a tool tip containing the fully qualified name of the element, the package in 

which the element resides, and the host name and port number of the server, rest the 

mouse pointer on the element name. 

You can clear the list of elements currently displayed in the Recent Elements tab by 

clicking Clear. 

Developer handles changes to the Recent Elements list as follows: 

� When you close an open element in the editor, Developer adds the element to the top 

of the Recent Elements list. 

� Developer remembers the contents of the Recent Elements tab between sessions. If 

you attempt to open an element that was deleted after you closed your previous 

Developer session, Developer alerts you that the element cannot be found and then 

removes the element from the list. 

� If you attempt to open an element listed in the Recent Elements tab that another user 

has deleted, moved, or renamed during your Developer session, Developer displays a 

message alerting you that the element cannot be found. 

If you move or rename an element during your current session, Developer 

automatically refreshes the Recent Elements tab to reflect the change. If you delete an 

element, Developer removes the element from the Recent Elements list. 

For more information about selecting elements in the Recent Elements tab to view or edit 

in the editor, see “Opening and Closing Elements in the Editor” on page 49. 


If you open 

an element from the 

Navigation panel... 

...editing controls for 

that element are 

displayed in the editor. 

The Editor 


The editor contains the controls that you use to examine and edit an element you open 

from the Navigation panel or Recent Elements tab. The contents of the editor vary 

depending on the type of element you select. 

For some element types, the editor is divided into multiple areas, including tabs 

containing additional editing controls for the element. You switch among areas within the 

editor just as you would between the Navigation panel or Recent Elements tab and the 

editor. To select a different area, click any white space in that area. To display the contents 

of a tab, click the tab name. 

Editing controls for an element 

In this example, a 

specification is opened in 

the editor. 

The editor lists the input 

and output fields that 

were created for this 

specification. These lists 

are also referred to as 

“trees.” 

As mentioned earlier, you can use the Navigation panel and Recent Elements tab to select 

one or more elements to view or edit in the editor. It is helpful to display multiple 

elements in the editor when you are editing an element and you would like to refer back 

to another element for information. For example, if you are creating or editing a trigger, 

you may want to quickly view the document types and services associated with that 

trigger. 

Each element you open has its own tab in the editor. The element’s title bar contains the 

fully qualified name of the element and icons to indicate the element’s type and lock 

status. For more information about these icons, see “Navigation Panel Icons” on page 25 

and “What Is a Lock?” on page 94. 


Each opened element in 

the editor has its 

own tab. 

The element’s title bar 

displays the element’s 

fully qualified name. 

Some elements have 

specialized tabs. 

Editor with multiple elements opened 

The Properties Panel 


Tip! You can press CTRL+ALT+RIGHT ARROW to toggle forward between open elements 

in the editor and CTRL+ALT+LEFT ARROW to toggle backward. 

Click to view tabs that are not currently visible. 

Click to close the active element 

(that is, the element that is currently 

displayed). 

Tip! You can locate the active element in the Navigation panel by using the Edit�Locate in 

Navigation command. 

The Properties panel displays the properties for the currently selected item in the 

Developer window. You use this panel to view and edit the properties of an item (such as 

an element, a step in a flow service, a field in a document, or a link between two 

variables). 

The properties that Developer displays in this panel vary depending on the item you 

select and which area of the Developer window has the focus. Developer identifies the 

item for which properties are displayed beneath the title bar of the Properties panel. 


Click to collapse the 

list of properties 

beneath a category. 

Click to expand the list 

of properties beneath 

a category. 

Properties panel 

Depending on the type of property you select, you edit a property by: 


Tip! If the Properties panel displays the properties for an item (for example, a document 

field) and you want to display the properties for its parent element (for example, the 

document type to which the field belongs), click the title bar of the parent element in the 

editor, the tab of the parent element in the editor, or the white space within the editor. 

Drag to resize the Property and 

Value columns. 

Name of the item for which properties are 

displayed. 

Properties are grouped 

into categories. 

Description of the 

selected property. 

� Typing a value in the box to the right of the property name (for example, to specify the 

namespace and local names that make up the universal name for a service) 

Tip! You can also paste text into the box that you previously copied to the clipboard. 

Note: Developer accepts the text you type in a property box when you move the focus 

outside of the box or press ENTER. You can cancel your edits before you perform 

either of these actions by pressing ESC. 

� Selecting a value from a list (for example, to specify a validation processing rule) 

� Clicking a button next to the property name and supplying values on a dialog box (for 

example, to specify an index when linking to or from an array variable) 

� Clicking the browse button to locate an element (for example, a service) 

The tips area beneath the list of properties includes a description of the selected property 

and its values. To obtain this information for a particular property, click the property 

name. 



Note: If you do not own the lock for an element, the element’s properties are read only. 

The Results Panel 

The Results panel shows the result of a service’s execution, the variables that a service 

adds to the pipeline, and the contents of those variables. You can use this panel to quickly 

examine the data produced by the service while you are testing and debugging the 

service. You can also save the data to a file and use it as input for a later test. 

Results panel 

For more information about service execution results, see Chapter 11, “Testing and 

Debugging Services”. 

Working in the Developer Window 

Moving Between Panels 

Click a variable name... 

...to view its contents in 

the pipeline at this stage 

of the service’s execution. 

Before you can perform an action on an item that is displayed in the Developer window, 

you must first select the panel in which that item appears (that is, give that panel the 

“focus”). You can only select one panel in the Developer window at a time. Developer 

indicates which area has the focus by highlighting the area’s title bar in blue. 



To switch from one panel of the Developer window to another, click any white space or 

field within the panel to which you want to switch. This action changes the focus to the 

new panel and makes its menu commands and toolbar buttons available for use. 

Performing Actions 

Before you can perform an action on an element, you must select the element in one of the 

following ways: 

� Single-click the title bar of an element in the editor. 

� Right-click an element. 

� Single-click one or more elements in the Navigation panel. 

Tip! To select a group of adjacent elements simultaneously, press the SHIFT key as you 

click. To select a group of non-adjacent elements, press the CTRL key. 

Note: Single-clicking an element in the Navigation panel selects (highlights) the 

element but does not open the element for viewing or editing in the editor. To open an 

element in the editor, double-click it. 

The actions that are available for an element depend on which area of the Developer 

window has the focus. For example, to run a service, the service must be open in the 

editor and have the focus. 

There are a number of ways to perform an action on an element after you select it: 

� Menu commands. You can select a command from the menu bar to perform an action on 

an element. For example, to save changes to an opened element using the menu bar, 

select the element in the editor and then click File�Save. 

You can also access menu commands on a shortcut menu by right-clicking the 

element. For example, to open an element using a shortcut menu, right-click the 

element in the Navigation panel and then click Open. To close an editor using a 

shortcut menu, right-click the editor title bar and then click Close Active Editor. 

� Toolbar buttons. You can click a toolbar button to perform an action on an element. For 

example, to save changes to an opened element using a toolbar button, select the 

element in the editor and then click . 

The toolbar buttons that are available for you to use depend on the item in the 

Developer window that currently has the focus. For example, when you are editing a 

flow service, the flow service toolbar buttons in the editor are not available unless the 

editor has the focus. 

� Keys. You can use the keyboard to access a menu by pressing the ALT key plus the 

underlined letter in the menu name. You can then select a command on that menu by 



pressing the underlined letter in the command’s title. For example, to save changes to 

an element using the keyboard, select the element, press ALT and F to access the File 

menu, and then press S to save the element. 

Some commands also have shortcuts assigned to them. These shortcuts are displayed 

to the right of their associated commands on the menu bar. For example, to save 

changes to an element using a keyboard shortcut, select that element and then press 

CTRL and S. 

� Drag-and-drop action. You can select an element and move it to another package or 

element, either on the same server or on a different server, by dragging it. For 

example, to move an IS document type from one folder to another, you would drag 

that document type to the new folder. 

Note: Some elements, such as adapter notifications, cannot be moved using the dragand-drop 

action. 

Most of the procedures in this guide instruct you to perform actions using menu 

commands. 

Resizing Areas in the Developer Window 

You can resize areas in the Developer window by: 

� Hiding or showing panels 

� Dragging the movable border between panels 

� Switching perspectives 

Hiding and Showing Panels 

You can hide and show panels on the Developer window as follows: 

To... Do this... 

Hide the Navigation 

panel, Servicenet tab, 

and Recent Elements 

tab 

Click along the left edge of the Developer window. 

Show the Navigation 

panel, Servicenet tab, 

and Recent Elements 

tab Click along the left edge of the Developer window. 



Hide the Properties 

and Results panels 

Show the Properties 

and Results panels 

Expand or collapse 

editor details 

Dragging Movable Borders 


You can resize areas in the Developer window by dragging the movable borders between 

panels with your mouse. 

Switching Perspectives 

You can quickly change the Developer window to tailor it to the task you are performing 

(for example, show only the editor and Results panel when you are testing a service) by 

displaying a particular perspective. Perspectives allocate more space on the Developer 

window for a particular task by hiding or minimizing the areas that are not essential to 

that task. 

Developer offers three perspectives: 

� Edit perspective. The edit perspective displays all of the Developer window areas but 

minimizes the Results panel. This perspective is useful when you are opening and 

editing elements and their properties. 

� Test perspective. The test perspective hides the Navigation panel, Servicenet tab, and 

Recent Elements tab and maximizes the editor and the Results panel. This perspective 

is useful when you are testing and debugging a service and you want to view the 

results of the service’s execution, its inputs and outputs, and its pipeline variables. 

� Details perspective. The details perspective hides the Navigation panel, Servicenet tab, 

and Recent Elements tab and minimizes the Results panel. This perspective is useful 

when you want to see as much of an element’s detail as possible (for example, a 

service’s pipeline). 

You display a perspective as follows: 

Click along the right edge of the Developer window. 

Click along the right edge of the Developer window. 

Click on the border between the top of the editor and the 

specialized tabs beneath it. 


Click to hide or show the 

Navigation panel, 

Servicenet taband 

Recent Elements tab. 

Click to expand or 

collapse editor details. 


To display the... Use this command... Or click this toolbar button... 

Edit perspective Window�Edit Perspective 

Test perspective Window�Test Perspective 

Details perspective Window�Details Perspective 

You can manually adjust areas within a perspective using the other techniques described 

in this section. Developer saves your settings across sessions. 

If you have adjusted the perspectives manually and you want to revert them to their 

default settings, use the Window�Reset Perspectives command. 

Resizing areas in the Developer window 

Opening, Closing, and Restoring Sessions 

Click to display Edit, 

Test, and Detail 

perspectives. 

Click to hide or show the 

Properties and Results 

panels. 

Drag movable borders 

to resize panels. 

When you start Developer you are prompted to log on to the server that you want to 

access. You maintain a session on that server until you exit Developer or close the session. 

You can have open sessions on multiple servers at a time. In the Navigation panel, the 

server that contains the selected element is the server on which your commands will be 



executed. For example, if you have the localhost:5555 server selected in the Navigation 

panel and you select the New command, the new element will be created on that server. 

You can open a session on another server without closing your current session by using 

the Session�Open command. 

To open a session on a different server 

1 On the Session menu, click Open. 

2 Complete the Open Session dialog box. For more information about completing this 

dialog box, see “To start Developer” on page 21. 

3 Click OK. 

Important! While you have an open session on a server through Developer, you are using a 

licensed seat for that server. At times when you are not actively using Developer, you may 

want to close your session to free a seat on the server for others to use. 

To close a session on the current server 

1 Save any work that you want to keep. 

2 On the Session menu, click Close. 

Restoring a Session on a Server 

Sometimes a server might shut down before you can save your work. Developer preserves 

any unsaved work as well as lock information, despite the loss of the connection to the 

server. When the server restarts, you can restore your session and save your changes to the 

server. 

Important! If a server shuts down and you close your session (that is, disconnect from the 

server), close unsaved elements on that server in the editor, or exit Developer before the 

server restarts, Developer warns you that if you continue you will lose all unsaved work. 

If you do not want to lose your work, click Cancel and wait for the connection to that 

server to be restored. 

To restore a session on the server 

� On the Session menu, click Restore. 



Note: Restoring a session is different from refreshing the session. Refreshing the session 

updates your screen to reflect the actions of other users on elements that are displayed 

within the Navigation panel and the editors. A refresh action does not restore the working 

state of an element if a server shuts down. For more information about refreshing the 

Navigation panel, see “Refreshing the Contents of the Navigation Panel” on page 27. 

Notification of Server Shutdown 

If the server administrator shuts down the server on which you have an open session, 

Developer does one of the following: 

� If the server administrator specified a time delay before shutdown, Developer 

displays a message notifying you when the shutdown process began and how many 

minutes remain before the server shuts down. After you receive notification of server 

shutdown, save any work that you want to keep and then close your session. If you do 

not close your session, Developer notifies you when the server has shut down. 

� If the server administrator performed an immediate shutdown, Developer displays a 

message stating that your connection to the server has been lost. (Developer also 

displays this message if the network connection to the server is lost.) 

If you did not save your work before shut down occurred, you might be able to restore 

your session when the server restarts and then save your work. For more information 

about restoring sessions, see “Restoring a Session on a Server” on page 38. 

Changing Your Password 

You can change the password for your user account. If you forget your password, contact 

the server administrator. 

Important! If you are outside of the corporate firewall, do not change your password unless 

you use SSL to open the session on the webMethods Integration Server. If you do not use 

SSL, your password can be exposed in unencrypted form. 

Note: You cannot use Developer to change passwords that are stored in an LDAP or NIS 

server. 

Password Requirements 

For security purposes, webMethods Integration Server places length and character 

restrictions on passwords. webMethods Integration Server contains a default set of 



password requirements; however, your server administrator can change these. For more 

information about these password requirements, contact your server administrator. 

The default password requirements provided by webMethods are as follows: 

Requirement Default 

Minimum length 8 

Minimum number of alphabetic characters 3 

Minimum number of uppercase characters 2 

Minimum number of lowercase characters 2 

Minimum number of numeric characters 1 

Minimum number of special characters (non-alphabetic and non-numeric 

characters, such as *. ?, &) 

1 

To ensure the security of your password, follow the additional guidelines below: 

� Do not choose obvious passwords, such as your name, address, phone number, 

license plate, spouse’s name, child’s name, or a birthday. 

� Do not use any word that can be found in the dictionary. 

� Do not write your password down. 

� Do not share your password with anyone. 

� Change your password frequently. 

To change your password 

1 On the Session menu, click Change Password. 

2 In the Change Password dialog box, in the Old Password field, type your current 

password. 

3 In the New Password field, type your new password. 

4 In the Confirm New Password field, retype your new password. Click OK. 

Important! The server administrator can disable the feature for changing your password 

from Developer. If the feature is disabled and you try to change your password, you will 

receive a message stating that the administrator has disabled the feature. 


Using Online Help 


You can access online help at any point in webMethods Developer. To open the help 

system and search for a topic of interest, click Contents from the Help menu. Developer also 

provides the following types of context-sensitive help: 

� Window areas. For help about the dialog box or Developer window area that currently 

has the focus, do one of the following: 

� Click the Help button (available in most dialog boxes). 

� Press F1. 

� From the Help menu, click On Topic. 

� On the Developer window toolbar, click . 

� Properties. For help about a property, click the property in the Properties panel. 

Developer displays a description of the property at the bottom of the Properties panel. 

� Built-in services. For a description of a built-in service within the WmART, WmDB, 

WmPKI, WmPRT, or WmPublic packages, do one of the following: 

� If you are browsing the services within a package in the Navigation panel, select a 

service and press F1. 

� If you have added a built-in service to a flow service using an INVOKE step, 

select the built-in service in the editor and press F1. 

� If you are browsing for a built-in service to add to a flow service, select the builtin 

service in the Select dialog box and press F1. 

You can also view or print descriptions of all built-in services from one location by 

clicking Help�Built-In Service Reference. 




Chapter 2. Managing Elements in the Navigation Panel 

� What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

� Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

� Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

� Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 

� Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

� Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

� Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

� Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 

� Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

� Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

� Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

� Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66 

� Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 


What Is an Element? 

Folders, services, 

triggers, specifications, 

IS document types, 

and IS schemas are 

elements. 

2. Managing Elements in the Navigation Panel 

An element is an item that exists in the Navigation panel in webMethods Developer. 

Elements include folders, services, specifications, IS document types, triggers, and IS 

schemas. In the Navigation panel, servers and packages are not considered to be elements. 

Elements in the Navigation panel 

The following table identifies where to go for more information about creating new 

elements and performing actions on those elements. 

For information about... See... 

Creating, opening, moving and 

copying, renaming, deleting, 

finding, and caching elements 

The sections in this chapter 

Locking elements Chapter 4, “Locking and Unlocking Elements” 

Checking elements in to and out of a 

third-party version control 

repository 

webMethods Version Control System Integration 

Feature Developer’s Guide in the directory: 

..\webMethods6\Developer\doc\guides 

Performing actions on packages Chapter 3, “Working with Packages” 


Creating New Elements 

When creating elements, keep the following points in mind: 


� You cannot create a new Java or C service unless all services of those types are 

unlocked, or locked by you, in the folder in which you want to create the new service. 

For details, see “Locking Java and C/C++ Services” on page 97. 

� The names of non-folder elements must be unique across all packages. If you try to 

create an element using a name that already exists at that level in any package, 

Developer creates the element and names it Untitled. 

� Developer places some restrictions on the characters you can use in element and 

package names. For more information about these restrictions, see “Guidelines for 

Naming Elements” on page 46. 

To create a new element 

1 On the File menu, click New. 

2 On the New dialog box, click the type of element you want to create and then click 

Next. 

3 Follow the prompts given by Developer for the type of element you are creating. 

When you have supplied all of the information that Developer needs to create the 

element, the Finish button becomes active. 

4 Click Finish. 

Tip! You can quickly create an element by clicking next to the New button on the toolbar 

and then clicking the element you want to create. Developer adds the element beneath the 

currently selected element, with a default name of Untitled. 

If you select multiple elements and then click this button, Developer offers only the All 

Choices option, which opens the New dialog box described in the procedure above. 

About Element Names 

The fully qualified name of an Integration Server element is composed of two parts: a 

folder identifier, consisting of the folder path in which the element resides, and the element 

name. The Integration Server represents elements in the following format: 

folder.subfolder1.subfolder2:element 



For example, if the HomeLoan service is in the Personal folder, which is contained in the 

Finance folder, the fully qualified service name is: 

Finance.Personal:HomeLoan 

Note: Developer ensures that the fully qualified name of each element within the server is 

unique. Depending on the action you are performing on the element, Developer 

accomplishes this either by alerting you that the action cannot be completed or by 

appending a number to the name of the element after the action is performed. For 

example, if you are copying a flow service named checkOrder2 to a destination that already 

contains a flow service with that name, Developer copies the service and names the copy 

checkOrder2_1. 

Package Names and Element Names 

The name of the package to which an element belongs has no bearing on the names of the 

elements that package contains (that is, the package name is not part of the fully qualified 

name of the element). Nor does it affect how the element is referenced by a client 

application. For example, if you move a service called Personnel:GetDeptNames from a 

package called Admin to a package called EmployeeData, client applications would still 

reference the service as Personnel:GetDeptNames. 

Guidelines for Naming Elements 

webMethods Developer places some restrictions on the characters you can use in element 

and package names. Specifically, element and package names cannot contain: 

� Reserved words and characters that are used in Java or C/C++ (such as for, while, and 

if ) 

� Digits as their first character 

� Spaces 

� Control characters and special characters like periods (.), including: 

? ' - # = ) ( . / \ ; 

& @ ^ ! | } { ` > < 

% * : $ ] [ " + , ~ 

� Characters outside of the basic ASCII character set, such as multi-byte characters 

If you specify a name that disregards these restrictions, Developer displays an error 

message. When this happens, use a different name or try adding a letter or number to the 

name to make it valid. 


Editing Elements 


To edit an element, you must first lock it. You must also have Write access to the element. 

For more information about locking and unlocking elements, see Chapter 4, “Locking and 

Unlocking Elements”. For more information about access permissions, see Chapter 5, 

“Assigning and Managing Permissions”. 

If you have enabled the VCS Integration feature, you must first check out the element 

before you can edit it. For more information, see the webMethods Version Control System 

Integration Feature Developer’s Guide in the ..\webMethods6\Developer\doc\guides 

directory. 

Tip! You can produce printable versions of many of the elements in the Navigation panel 

by clicking File�View as HTML. 

Specifying Dependency Checking Safeguards 

Developer automatically checks for dependents when you delete, rename, or move 

elements in the Navigation panel. This dependency checking acts as a safeguard to 

prevent you from inadvertently affecting other elements on the webMethods Integration 

Server. This is especially important during collaborative development on the same 

webMethods Integration Server. 

You can have Developer prompt you before deleting, moving, or renaming an element 

with dependents. You can also have Developer update local references when pasting 

elements. 

Note: The dependency checking options are enabled by default. 

To specify dependency checking safeguards 

1 On the Tools menu, click Options. 

2 Click General. Under Navigation Panel, do the following: 


Select... To... 

3 Click OK. 


Confirm before deleting Instruct Developer to notify you before deleting an 

element used by other elements, such as flow services, IS 

document types, specifications, or triggers. 

Prompt before updating 

dependents when 

renaming/moving 

Update local references 

when pasting multiple 

elements 

For more information about finding dependents, see “Finding Dependents and 

References” on page 63. 

Notes About Performing Actions on Elements 

If Developer finds elements that depend on the element 

being deleted, Developer lists those dependents and 

prompts you to delete the element anyway or cancel the 

action. If you clear this check box, Developer deletes the 

element without prompting you. 

Instruct Developer to alert you when dependents (that is, 

other elements that use the selected element, such as 

flow services, IS document types, or triggers) exist. 

If dependents exist, Developer lists those dependents 

before renaming or moving the selected element and 

prompts you to: 

� Rename/move the selected element and update 

references in dependent elements. 

� Rename/move the selected element without 

updating references to it. 

� Cancel the action. 

If you clear this check box, Developer automatically 

updates dependents without prompting you. 

Instruct Developer to update references when copying 

and pasting a group of elements that refer to each other. 

If you clear this check box, Developer retains the original 

references in the copied elements. 

When performing actions on one or more elements, keep the following points in mind: 

� You must have at least List access to view elements, Read access to select elements to 

move or copy, Write access to the location to which you want to move/copy elements, 

and Write access to elements you want to rename or delete. If you select multiple 



elements and you do not have the required access to one or more of them, you will not 

be able to perform the action. You must either ask your system administrator to give 

you the required access to the elements or select only elements for which you have the 

proper access. 

� Developer prompts you to save changes to an element before allowing you to perform 

an action on the element, close the element in the editor, close your session on the 

current server, or exit Developer. 

� The actions you can perform on items depend on the type and combination of items 

you select. If an action is not allowed for one or more elements in a selection, 

Developer makes the action unavailable for use. For example, Developer disables the 

cut, copy, paste, and delete actions if you select a server. Developer also prevents you 

from selecting multiple elements when doing so could cause confusion or undefined 

results. For example, you cannot select a server and any other element, a package and 

any other element, or a folder and one or more elements contained within that folder. 

� If you select multiple elements and Developer encounters an error while performing 

the specified action on one or more of the elements, Developer displays a dialog box 

listing the elements for which the action failed. You can obtain more information 

about why the action failed by clicking Details. 

� The elements you want to move, copy, rename, save, or delete must be unlocked, or 

locked by you. For more information about locking and unlocking elements, see 

Chapter 4, “Locking and Unlocking Elements”. 

� You cannot undo a move, copy, rename, or delete action using the Edit�Undo 

command. 

� If you select a publishable document type that is associated with an adapter 

notification, Developer handles actions performed on the document type as follows: 

� For non-copy actions, you must also select the adapter notification before you can 

perform a non-copy action on the document type. 

� For copy actions, you can select the publishable document type without selecting 

its associated adapter notification. However, the copied publishable document 

type loses its association with the adapter notification. 

Opening and Closing Elements in the Editor 

You can open elements from either the Navigation panel or the Recent Elements tab. 

When opening elements from the Navigation panel, keep the following points in mind: 

� Single-clicking an element selects the element but does not display its details in the 

editor. Double-clicking an element opens it in the editor. 



� Double-clicking a folder expands or collapses the contents of the folder in the 

Navigation panel. To view a folder’s properties in the Properties panel, perform the 

steps in the procedure that follows. 

� If the Developer’s Version Control System (VCS) Integration feature is enabled, 

Developer might exhibit slowdowns, error messages (such as "Server version has 

changed" and "Session already in use"), and may stop responding completely when 

you expand a large element (such as a folder) in the Navigation panel. This condition 

occurs when Developer queries the Integration Server to check the lock state of each 

element within an element. To improve performance during lock checking, see 

“Optimizing Lock Checking” on page 77. 

To open elements in the editor 

1 Select one or more elements to open. 

Tip! Press the SHIFT key as you click to select a group of adjacent elements. Press the 

CTRL key to select a group of non-adjacent elements. 

2 On the File menu, click Open. 

If you are opening an element from the Recent Elements tab and the element resides 

on a server to which you are no longer connected, Developer prompts you to log on to 

that server before displaying the element. 

To close elements in the editor 

� Do one of the following: 


Close the active element in the editor 

(that is, the element whose tab is 

highlighted) 

On the Window menu, click Close Active 

Editor. 

Close all elements except the active one On the Window menu, click Close All But 

Active Editor. 

Close all elements in the editor On the Window menu, click Close All 

Editors. 

Note: You do not need to close elements when you exit Developer. Developer remembers 

which elements were open and displays them when you restart Developer. If you close an 

element without saving changes made to the element, Developer will prompt you to save 

changes. 


Moving and Copying Elements 


You can move or copy elements between packages and, in most cases, across servers. 

When moving or copying elements, keep the following points in mind: 

General 

� You must have Read access to the elements you are moving or copying and Write 

access to the packages, folders, or servers to where you want to move/copy them. For 

more information about Write access and ACLs assigned to elements, see Chapter 5, 

“Assigning and Managing Permissions”. 

� When you move or copy an element, Developer automatically changes the element’s 

fully qualified name to reflect its new location. 

� You cannot move an element to a location that already contains an element with the 

same name. If you copy the element, however, Developer copies the element and 

appends a number to the end of the name of the copied element. 

� You cannot move multiple elements with the same name to a single location. 

� After you move or copy an element, the element becomes locked by you. 

� When you copy multiple elements to another location on the same server and the 

elements contain references to each other, Developer updates the references if you 

have selected Update local reference(s) when pasting multiple elements on the Options 

dialog box. For example, if you copy a folder that contains two services and one of the 

services invokes the other, Developer will update the reference to the invoked service. 

Moving and Copying Services 

� When you move or copy a service, Developer does not move/copy any output 

templates that are associated with that service. 

� If you move a service, or a folder containing a service, Developer retains the service’s 

explicit universal name. If you copy a service or a folder containing a service, 

Developer does not retain the service’s explicit universal name. You must restore the 

universal name by editing the service’s properties. For more information, see 

“Assigning Universal Names to Services” on page 145. 

� When you move or copy a Java service, Developer automatically recompiles the 

service and any Java services that remain in the source folder. When you delete a Java 

service, Developer recompiles any Java services that remain in the source folder. 

� You cannot move or copy a Java service to a folder that contains other Java services 

that are system locked or locked by another user. If you attempt to do so, Developer 

cancels the entire move/copy action. 

� When you move or copy a Java service, Developer will also move or copy the service’s 

Shared fields to the destination folder, unless the destination folder already contains 



Shared fields with different values. In this case, you must first manually copy the 

Shared fields into the destination folder and then move or copy the Java service. 

Copying Elements Between Servers 

� When you cut and paste or drag elements between servers, Developer retains a copy 

of the elements on the source server. That is, a move (cut and paste or drag) action is 

the same as a copy action. 

� Developer does not automatically copy an element’s references to the destination 

server. Instead, it displays a dialog box after the copy alerting you to any unresolved 

references. You must copy the references to the destination server manually. 

� Developer does not automatically update references when copying across servers. 

Therefore, if you are copying multiple elements from one server to another using 

Developer and the elements reference each other, you should paste the elements into a 

location with the same name on the destination server. 

� If you are copying an add-in element that has a component that resides on the server, 

and the destination server does not have that add-in component installed, Developer 

displays an error message stating that you are attempting to copy an unknown 

element. Developer does not copy the add-in elements but does copy other elements 

in the selection. 

� Elements you copy to a folder on a different server adopt the ACL access permissions 

of the destination folder, even if they had explicitly assigned ACLs on the source 

server. Folders you copy to a package on a different server inherit the default ACLs 

for top-level folders. 

� When you copy a trigger to another server, the trigger will be pasted in a disabled 

state. To create the subscriptions identified in the trigger, you must enable the trigger. 

When you copy a package to another server, the triggers contained in the package will 

maintain their original state. 

If you are configuring a cluster, use the package replication feature in the Integration 

Server Administrator to populate the cluster nodes. See the webMethods Integration 

Server Administrator’s Guide for more information about this feature. 

� When you move or copy a publishable document type to a destination on the same 

server, the moved or copied document type remains publishable. When you copy a 

publishable document type to a different server, Developer converts the publishable 

document type to an IS document type on the destination server. For more 

information about making IS document types publishable and synchronizing them 

with Broker document types, see the Publish-Subscribe Developer’s Guide. 


Moving and Copying Adapter Notifications and Related Elements 


Tip! To retain the status of a publishable document type and its link to a Broker 

document type, use the package replication functionality in the Integration Server 

Administrator instead of using Developer to move or copy the package containing the 

publishable document type. For information about package replication, see the 

webMethods Integration Server Administrator’s Guide. 

� Although you cannot move an adapter notification’s publishable document type 

without also moving its associated adapter notification, you can copy it. If you do so, 

the copied document type remains publishable but is no longer associated with the 

adapter notification. 

When you move or copy an adapter notification, Developer also moves/copies its 

associated publishable document type and prompts you to indicate whether to 

move/copy the associated Broker document type. 

� You cannot move or copy adapter notifications, adapter notification publishable 

document types, or adapter services across servers. If you are selecting multiple 

elements and your selection contains any of these elements, Developer alerts you that 

the move/copy action cannot be completed. 

� You cannot move or copy a listener or connection element. 

To move or copy elements 

1 Select the elements that you want to move or copy. 

2 Do one of the following: 

To... Click... 

Cut the element Edit�Cut 

Copy the element Edit�Copy 

Tip! You can cancel a cut action by pressing ESC. 

3 If the elements you want to move or copy contain unsaved changes, Developer alerts 

you that you must first save the changes. Click OK to close the alert dialog box. Then, 

save the changes and repeat the move/copy action. 

4 If you do not have Read access to the elements you are moving or copying, or Write 

access to the location you are moving/copying them to, Developer displays a message 

that identifies the elements that are preventing the action from completing 

successfully. Click OK and then either obtain the proper access from your system 

administrator or select only those elements to which you have proper access. 



5 Select the location where you want to move or copy the elements. 

6 On the Edit menu, click Paste�After. 

7 If the destination already contains an element with the same name as an element you 

are moving or copying, do one of the following: 

� If you are moving the element, Developer alerts you that the element cannot be 

moved. Click OK to close the alert dialog box. Rename the element if desired and 

repeat the move action. 

� If you are copying the element, Developer copies the element and appends a 

number to the name of the copied element. (For example, if you are copying a 

flow service named checkOrder2 to a destination that already contains a flow 

service with that name, Developer copies the service and names the copy 

checkOrder2_1.) Rename the element if desired. 

For more information about renaming elements, see “Renaming Elements” on 

page 55. 

8 If one of the elements you moved or copied is a Java service, perform the following as 

necessary: 

� If you are moving or copying the Java service to a folder with other Java services 

that are system locked or locked by another user, Developer alerts you that the 

element cannot be moved/copied. 

Click OK and then ask the owner of the lock to remove the lock. 

� If the Java service you are moving or copying contains a shared source that 

conflicts with the shared source of an existing Java service in the destination 

folder, Developer alerts you that there is a conflict. Click Proceed to use the 

destination folder’s shared source, or click Cancel to cancel the entire move action. 

Note: If no shared Java source conflict exists, Developer moves the Java service and 

its shared source to the destination folder. If a conflict does exist, you must respecify 

the Shared tab information in the copy of the service. (You can copy the 

information from the Shared tab for the original service to the Shared tab for the 

copy of the service.) 

9 If you clicked the Prompt before updating dependents when renaming/moving check box in 

the Options dialog box and any elements on the current server contain unsaved 

changes, Developer prompts you to save the element(s). Do one of the following: 


Save changes and then proceed with the move/copy action Save and Proceed 

Proceed with the move/copy action without saving 

changes 

Proceed without Save 


Renaming Elements 



Cancel the entire move/copy action Cancel 

10 If you clicked Proceed without Save in Step 9, Developer identifies the elements that will 

be affected by the move. 

Do one of the following: 


Move the selected element and update references to 

dependent elements 

Move the selected element in the Navigation panel 

without updating references to dependent elements 

Cancel the entire move action Cancel 

For more information about dependency safeguards, see “Specifying Dependency 

Checking Safeguards” on page 47. 

When renaming elements, keep the following points in mind: 

Update Usages 

Ignore Usages 

Tip! You can also move elements by clicking them and dragging them to their new 

location. 

� You can rename any elements for which you have Write access to the element and its 

parent folder. When renaming a folder, you must also have Write access to all 

elements within the folder. For more information about Write access and ACLs 

assigned to elements, see Chapter 5, “Assigning and Managing Permissions”. 

� When you rename a folder, Developer automatically renames all of the elements in 

that folder (that is, changes their fully qualified names). 

� If the folder you want to rename contains elements with unsaved changes, you must 

save the changes before you can rename the folder. 

� Element names must be unique across all packages. If you try to rename an element 

using a name that already exists at that level in any package, Developer reverts the 

element back to its original name. 



� When you rename an adapter notification, Developer also renames its associated 

publishable document type and prompts you to indicate whether to rename the 

associated Broker document type. 

� You cannot rename a listener or connection element. 

To rename an element 

1 Select the element that you want to rename. 

2 On the Edit menu, click Rename. 

3 If the element you want to rename contains unsaved changes, Developer alerts you 

that the element cannot be renamed until you save the changes. Click OK to close the 

alert dialog box. Then, save the changes and repeat the rename action. 

4 Developer moves the cursor to the end of the element name. Edit the name and press 

ENTER. 

If an element already exists with that name at the same level, Developer displays a 

message alerting you that the rename action could not be completed. Click OK to close 

the message dialog box and repeat the rename action. 

Tip! You can cancel a rename action by pressing ESC. 

5 If you clicked the Prompt before updating dependents when renaming/moving check box in 

the Options dialog box and any elements on the current server contain unsaved 

changes, Developer prompts you to save the element(s). Do one of the following: 


Save changes and then proceed with the rename action Save and Proceed 

Proceed with the rename action without saving changes Proceed without Save 

Cancel the entire rename action Cancel 

6 If you clicked Proceed without Save in Step 5, Developer alerts you to the elements that 

will be affected by the rename action. 

Do one of the following: 


Rename the selected element in the Navigation panel and 

update references to dependent elements 

Update Usages 





Saving Changes to Elements 

Deleting Elements 


Rename the selected element without updating references to 

dependent elements 

Cancel the entire rename action Cancel 

Changes that you make to an element are not written to webMethods Integration Server 

until you explicitly save your work. 

To save changes to elements 

� Do one of the following: 


If you attempt to close Developer, close your session on the current server, close an 

unsaved element in the editor, or perform an action on an element without saving your 

changes, Developer will prompt you to save changes first. 

When deleting elements, keep the following points in mind: 

Ignore Usages 

Save changes to the current element On the File menu, click Save. 

Save all elements you have edited, on 

all servers 

On the File menu, click Save All Editors. 

� You can delete any elements to which you have Write access for the element and its 

parent folder. When deleting a folder, you must also have Write access to all elements 

within the folder. For more information about Write access and ACLs assigned to 

elements, see Chapter 5, “Assigning and Managing Permissions”. 

� When you delete a folder or the last Java service in a folder, Developer also deletes the 

shared source for that folder. If you cancel the delete action, no elements (including 

non-Java service elements) are deleted. 

� You can only delete an adapter notification’s publishable document type if you delete 

its associated adapter notification. 



� When you delete an adapter notification, Developer also deletes its associated 

publishable document type and prompts you to indicate whether to delete the 

associated Broker document type. 

� You cannot delete a listener or connection element. 

To delete elements 

1 Select the elements that you want to delete. 

2 On the Edit menu, click Delete. 

3 If you selected the Confirm before deleting check box in the Options dialog box, do the 

following: 

a If any elements on the server contain unsaved changes, Developer prompts you to 

save the element(s). Do one of the following: 


Save changes and then proceed with the delete 

action 

Proceed with the delete action without saving 

changes 

Cancel the entire delete action Cancel 

Save and Proceed 

Proceed without Save 

b If the elements you are deleting are not dependents of other elements, Developer 

prompts you to confirm the delete action. Click OK. 

c If the elements you are deleting are dependents of other elements, Developer 

alerts you to the elements that will be affected by the deletion. Do the following: 

1 If one of the elements you want to delete is a publishable document type or an 

adapter notification, do one of the following: 


Delete the element on the Integration 

Server but leave the corresponding 

document type on the Broker 

Delete the element on the Integration 

Server and the corresponding 

document type on the Broker 

Clear the Delete associated Broker 

document type on the Broker check 

box. 

Select the Delete associated Broker 

document type on the Broker check 

box. 


2 Continue or cancel the delete action as follows: 




Finding Elements and Fields 

Important! If you delete a publishable document type and Broker document 

type associated with a trigger or a flow service, you might break any 

integration solution that uses the document type. 

If you delete the Broker document type, you might negatively impact any 

publishable document types created from that Broker document type on 

other Integration Servers. When the developers synchronize document 

types with the Broker and they choose to Pull from Broker, publishable 

document types associated with the deleted Broker document type will be 

removed from their Integration Servers. 


Delete the elements from the Navigation panel 

(and therefore break any links to dependent 

elements) 

You can find elements and fields within Developer using the following methods: 

� Find elements in the Navigation panel. When creating and editing elements, you might 

lose track of where you saved certain elements. For example, suppose that you do not 

remember the folder to which you saved a service called Test. 

� Find fields in editor trees. You can search for fields in certain trees in the editor (that is, 

from within a document or specification editor, and in a flow service’s Pipeline tab). 

You might want to search for fields when working with a large document with many 

fields. 

� Locate an invoked service from the editor. You can highlight the location of an invoked 

service in the Navigation panel. This is especially helpful when working with a flow 

written by another party and with complex flows that make multiple invokes. 

Finding Elements in the Navigation Panel 

Continue 

Cancel the entire delete action Cancel 

Using the Find command, you can search across all packages and folders within a server to 

find all occurrences of a specified element name. 



The Find command searches the fully qualified names of elements. If you search for the 

name Test, the results display all elements with Test in their fully qualified name. The 

results could include a service called Sample located in a Test folder, or an IS document type 

called SampleTest. 

The Find command interprets search terms as case-sensitive regular expressions. By 

default, the command looks for all elements containing a specified search term. For 

example, if you specified “Test” as a search term, the results would include elements 

named “Test,” “MyTest,” and “TestFinal.” You can also include regular expression 

operator characters. For example: 

To find... Type... 

All elements containing “PO” PO 

All elements starting with “PO” ^PO 

All elements ending with “PO” PO$ 

All services with the exact name of “logPO” :logPO$ 

All elements containing “log” followed by any 

two characters (wildcards) 

log.. 

For a complete list of regular expression operator characters, see Appendix B, “Regular 

Expressions”. 

Note: The Find command supports regular expressions but not conditional statements. For 

example, you can specify Test as a search term, but not Test OR Test1. 

To find an element in the Navigation panel 

1 Click anywhere in the Navigation panel. 

2 On the Edit menu, click Find. Developer displays the Find In Navigation Panel dialog 

box. 

3 In the Find In Navigation Panel box, type any portion of the fully qualified name of the 

element that you want to find. 

4 If you want to limit the scope of the search to a specific package, select the package in 

the Package list. 

5 Click Find. The Find In Navigation Panel dialog box displays the results of the search. 


The term “PO” is 

found in... 

...the names of 33 

elements in the 

Navigation panel. All 

of these elements 

contain “PO” in their 

fully qualified name. 

Results of search for “PO” 


6 To jump to an element in the Navigation panel, select that element in the results and 

click Go To. 

Note: If you receive a “Couldn’t find in Navigation panel” message when you click Go To, 

you probably do not have List access to the element. Contact your server administrator to 

obtain access. 

Tip! For an active element in the editor, you can highlight the element’s location in the 

Navigation panel using the Edit�Locate in Navigation command. 

Finding Fields in Editor Trees 

You can search for a field in any of the following trees in the editor: 

� Trees in a document or specification editor 

� Trees in the Pipeline In, Pipeline Out, Service In, and Service Out areas in the Pipeline tab of 

a flow service editor 

When searching for fields on an editor tree, keep the following points in mind: 

� You can search only one tree at a time. For example, if you want to find fields that 

contain the text number in the Pipeline In and Service In areas of the Pipeline tab, search 

one tree, and then the next. 

� You can refine your search by requiring Developer to find only fields that match the 

capitalization of the search text or fields that match only the complete word specified 

as the search text. 



� You can search for a parent and child field combination. For example, if you specify 

address/street as the search text, Developer searches for all instances where a field 

named street is a child of a document or document list field named address. If you 

specify customerInformation/address/street as the search criteria, Developer 

searches for a field named customerInformation that contains a field named address 

which contains a field named street. Use a forward slash (/) to separate the parent field 

from the child field. 

� Developer does not treat search text as a regular expression. For example, if you type 

^PO, Developer searches for fields that contain the text ^PO. Developer does not 

search for fields that begin with the text PO. 

Note: Developer interprets the forward slash character (/) as the divider between the 

name of a parent field and a child field. Developer will not search for a field name that 

contains a forward slash character. For example, if you type true/false as the search 

text, Developer searches for a field named false that is a child of a document or 

document list field named true. Developer does not search for a field named true/false. 

� Developer searches the tree as follows: 

� If you select a field, Developer begins searching at the selected field and continues 

to the bottom of the tree. If you have not selected a field, Developer begins 

searching at the top of the tree. 

� When Developer finds a field that matches the search criteria, Developer selects 

the field in the tree. 

� When Developer reaches the bottom of the tree, Developer displays a message 

asking if you would like to continue searching from the top of the tree. 

� After completing a search of the entire tree, if Developer cannot find a matching 

field, Developer displays a message stating that the search text was not found. 

To find a field within an editor tree 

1 Select the tree in which you want to search for a field. 

2 On the Edit menu, click Find. 

3 In the Find what field, type the text you want to search for. If you want to search for a 

parent-child field combination, use a forward slash (/) to separate the parent field 

from the child field. 


4 To further refine your search, do one or more of the following: 


Find fields with the same capitalization as 

the text in the Find what field 

Find only fields that match the complete 

word in the Find what field 

Find fields that contain the text in the Find 

what field as all or a portion of their name 


5 Click Find Next. If Developer finds a match, it selects the field and displays it on the 

Pipeline tab. 

6 Click Find Next to find the next field that matches the search criteria. 

Locating Invoked Services 

You can navigate to the location of an invoked service in both the flow view. 

To find an invoked service 

1 In the editor, select the INVOKE step containing the service you want to locate. 

2 On the Edit menu, click Locate in Navigation. Developer locates and selects the service in 

the Navigation panel. 

Finding Dependents and References 

Before performing an action on a selected element, you can determine whether other 

elements will be affected by the change by finding dependents and references of the 

element. In Developer, a dependent is an element that uses a selected element, and a 

reference is an element that is used by a selected element. 

Finding Dependents 

Select the Match case check box. 

Select the Match whole words check 

box. 

Clear the Match whole words check 

box. 

To determine how a selected element is used by other elements on the server, you can find 

dependents of the selected element. For example, suppose that the flow service ServiceA 

invokes the flow service receivePO. The ServiceA service uses (that is, is a dependent of) the 

receivePO service. If you delete receivePO from the Navigation panel, ServiceA will not run. 


This service is a 

dependent of... 

...each of these 

services. 

The services:receivePO 

service is used by... 

...this element. 

Dependent elements 


During debugging, you might want to locate all of the dependents of a given service or IS 

document type. Or, before editing an IS document type, you might want to know what 

elements, such as specifications, triggers, or flow services, will be affected by changes to 

the IS document type. Use the Find Dependents command to find all the dependents. 

Note: Developer does not consider a Java service that invokes another services to be a 

dependent. For example, if Java service A invokes service B, and you instruct Developer to 

find dependents of service B, service A will not appear as a dependent. 

To find dependents of a selected element 

1 In the Navigation panel or in the editor, select the element for which you want to find 

dependents. 

2 On the Tools menu, click Find Dependents. 

The Find Dependents dialog box displays the dependents of the element. 

Find Dependents dialog box 


Each of these services 

is a reference of 

ServiceA. 


3 After Developer finds the dependents of the selected element, you may do any of the 

following: 

� To jump to an element in the Navigation panel, select that element in the results 

and then click Go To. 

� To see all dependents of a found dependent, click next to the item in the results 

list. 

� To limit the scope of the search to a specific package, select the package in the 

Package list and then click Find. 

Finding References 

To determine how a selected element uses other elements on the server, you can find 

references of the selected element. For example, the flow service ServiceA invokes the 

services receivePO, pub.schema:validate, processPO and submitPO. Additionally, in its input 

signature, ServiceA declares a document reference to the IS document type PODocument. The 

services receivePO, validate, processPO, and submitPO, and the IS document type PODocument, 

are used by (that is, they are references of) ServiceA. 

Elements as references 

During debugging of a complex flow service, you might want to locate all of the services, 

IS document types, and specifications used by the flow service. Use the Find References 

command to locate the references. 

You can also use the Find References command to locate any unresolved references. An 

unresolved reference is an element that does not exist in the Navigation panel yet is still 

referred to in the service, IS document type, or specification that you selected. The element 

might have been renamed, moved, or deleted. To prevent unresolved references, specify 

the dependency checking safeguards. For more information about these safeguards, see 

“Specifying Dependency Checking Safeguards” on page 47. 

Note: Developer does not consider document references to schema types to be references, 

nor does it consider services invoked within a Java service to be references of the Java 

service. For example, if Java service A invokes service B, and you instruct Developer to 

find references for service A, service B will not appear as a reference of A. 


The processPO 

service uses... 

...these elements. 

The element in bold 

italics does not exist in 

the Navigation panel 

To find references of a selected element 


1 In the Navigation panel or in the editor, select the element for which you want to find 

references. 

2 On the Tools menu, click Find References. 

The Find References dialog box displays the references of the element. Unresolved 

references are indicated in bold italics. 

Find References dialog box 

3 After Developer finds the references of the selected element, you may do either of the 

following: 



� To see all references of a found reference, click next to the item in the results 

list. 

Inspecting Pipeline References 

A pipeline reference is where a Link, Drop, or Set Value pipeline modifier is assigned to a field 

in a document reference or document reference list on the Pipeline tab. For example, in its 

input signature, ServiceA declares a document reference to the IS document type 

PODocument. If ServiceA contains an INVOKE or MAP step in which a field in the document 

reference is linked to another pipeline variable, then that link is a pipeline reference. In the 

following illustration of the Pipeline tab, the link between PoNum and num is a pipeline 

reference. 


This variable is a 

reference to the 

PODocument in the 

Navigation panel. 

The link between 

PONum and num is a 

pipeline reference. 

This Drop Value 

modifier and... 

... this Set Value modifier 

are pipeline references. 

Pipeline reference 


Pipeline references are also those locations where you assign a Set Value modifier or a 

Drop Value modifier to a field in a document reference or document reference list. The 

following illustration of the Pipeline tab identifies these types of pipeline references. 

Examples of pipeline references 

When you edit an IS document type, the changes affect any document reference and 

document reference list variables defined by that IS document type. The changes might 

make pipeline references invalid. For example, suppose the input signature for ServiceA 

contains a document reference variable POInfo based on the IS document type PODocument. 

The IS document type PODocument contains the field PONum. In the pipeline for ServiceA, 

you link the PONum field to another pipeline variable. If you edit the PODocument IS 

document type by deleting the PONum field, the pipeline reference (the link) for the field 

in the ServiceA pipeline is broken (that is, it is invalid) because the pipeline contains a link 

to a field that does not exist. 



When you edit an IS document type, you might want to check all dependent pipeline 

modifiers for validity. You can use the Tools�Inspect Pipeline References command to locate 

any broken or invalid pipeline references. You can use this command to: 

� Search for invalid pipeline references in a selected flow service. 

� Search for invalid pipeline references involving document reference and document 

reference list variables defined by a selected IS document type. 

When inspecting pipeline references, keep the following points in mind: 

� You can inspect pipeline references in a selected flow service. You can also inspect 

pipeline references for document reference or document reference list variables based 

on a selected IS document type. The search results include only flow services, 

document reference variables, or document reference list variables that contain 

invalid pipeline modifiers. 

� Values set at the top level of a document reference or document reference list in the 

pipeline are not considered pipeline references. (That is, a Set Value modifier 

assigned to the document reference is not a pipeline reference.) Therefore, if a Set 

Value modifier assigned to a document reference contains input values for a 

nonexistent field, it will not appear in the search results even though it is invalid. 

� The search results will not show data type and dimensionality mismatches. For 

example, suppose that you link a String named Number to the PONum String list 

within the document reference PODocument. This dimensionality mismatch will not 

appear in the search results. 

� When you inspect pipeline references in a flow service, Developer inspects references 

across all packages on webMethods Integration Server. 

� When you inspect pipeline references for an IS document type, you can inspect 

references across a specific package or all packages. 

To inspect pipeline references 

1 In the Navigation panel or in the editor, select the flow service or IS document type 

for which you want to find invalid pipeline references. 

2 On the Tools menu, click Inspect Pipeline References. 

The Inspect Pipeline References dialog box displays all invalid pipeline references for 

the selected service or IS document type. 

� If you inspected a flow service, the search results contain all of the document 

references that have invalid pipeline references in that flow. 

� If you inspected an IS document type, the search results contain all of the flow 

services that have invalid pipeline references to that IS document type. 


The getData flow 

service contains... 

...an invalid reference in 

its pipeline to the IS 

document type po_doc. 

Inspect Pipeline References dialog box 


3 After Developer finds the pipeline references of the selected element, you may do any 

of the following: 



� To jump to the unresolved reference in the pipeline, select the element in the 

results and then click Find in Flow. 

� If the selected element has multiple unresolved references in the same flow 

service and you want to automatically jump to the next reference within the 

selected element, you can use the Find Next command. To use the Find Next 

command, keep the Inspect Pipeline References dialog box open and click Edit � 

Find Next. 

� If the selected element is a document type and you want to limit the scope of the 

search to a specific package, select the package in the Package list and then click 

Inspect. 


Caching Elements 


You can improve performance in Developer by caching Navigation panel elements that 

are frequently used. When elements are located in the Developer cache, Developer does 

not need to request them from the Integration Server and can therefore display them more 

quickly. 

To cache elements 

1 On the Tools menu, click Options. 

2 In the Options dialog box, click General. 

3 Under Navigation Panel, in the Number of elements to cache box, type the number of 

elements that you want to cache per Developer session. The total number of cached 

elements includes elements on all the servers to which you are connected. 

The minimum number of elements is 10. The higher the number of elements, the more 

likely an element will be in the cache, which reduces network traffic and speeds up 


4 Click OK. The caching settings take effect immediately. 

If you enter an illegal cache size Developer displays an error and resets the cache size 

to the previous value. 

Note: Keep in mind that increasing the cache reduces the amount of available memory. If 

you experience memory problems, consider decreasing the number of cached elements. 

Clearing the Developer Cache 

When you clear the Developer cache, you remove Navigation panel elements from 

memory for all servers. The following elements are not removed: 

� Flow services with breakpoints (if you want to clear the flow service from the cache, 

remove the breakpoint and clear the cache again) 

� Flow services that are currently being debugged (for example, if a service has been 

stepped into) 

� Unsaved elements 

Keep in mind that the cache is automatically cleared when you close Developer or when 

you refresh the session by using the Session�Refresh command. 


To clear the Developer cache 


1 On the Tools menu, click Options. Developer displays the Options dialog box. 

2 Click General. 

3 Under Navigation Panel, click the Clear Cache button. All cached elements are removed 

from memory. 

Note: Clearing cached elements from Developer is different from clearing the contents of 

the pipeline from webMethods Integration Server cache. If you want to clear the contents 

of the pipeline from a server’s cache, see “Configuring a Service’s Use of Cache” on 

page 138. 




Chapter 3. Working with Packages 

� What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

� Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

� Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 


What Is a Package? 

Package Management 

3. Working with Packages 

A package is a container that is used to bundle services and related elements, such as 

specifications, IS document types, IS schemas, and output templates. When you create a 

folder, service, specification, IS document type, IS schema, or output template, you save it 

in a package. 

Packages are designed to hold all of the components of a logical unit in an integration 

solution. For example, you might group all the services and files specific to a particular 

marketplace in a single package. By grouping these components into a single package, 

you can easily manipulate them as a unit. For example, you can copy, reload, distribute, or 

delete the set of components (the “package”) with a single action. 

Although you can group services using any package structure that suits your purpose, 

most sites organize their packages by function or application. For example, they might put 

all purchasing-related services in a package called “PurchaseOrderMgt” and all timereporting 

services into a package called “TimeCards.” 

On the server, a package represents a subdirectory within the 

webMethods6\IntegrationServer\packages directory. All the components that belong to a 

package reside in the package’s subdirectory. 

Note: Every element in webMethods Developer must belong to a package. 

For a list and description of packages installed with the Integration Server, see the 


You can use webMethods Developer to perform certain package management tasks, such 

as creating, copying, and deleting packages, on the Integration Server. When you perform 

a package management task, all of the files and services in the package are affected. 

The following table identifies all of the package management tasks that can be performed 

using Developer or the Integration Server Administrator. If you can perform the task with 

Developer, the See column directs you to a page within this guide for instructions. For 

tasks that can only be performed using the Integration Server Administrator, the See 

column directs you to the webMethods Integration Server Administrator’s Guide. 

To... See... 

Create a package page 76 

Activate a package webMethods Integration Server 

Administrator’s Guide 

Copy a package to another server page 78 


To... See... 

View details for a package page 77 

Display specific packages by filtering the 

Packages List 

Document the purpose and function of a 

package 

webMethods Integration Server 


page 80 


View the patch history for a package page 83 and 



Assign startup, shutdown, or replication page 88 

services to a package 

Reload the services and files in a package 

into memory without restarting the server 

page 81 and 



Delete the contents of a package page 81 and 



Assign a version number to a package page 83 and 



Identify packages that must be loaded page 85 

before a specific package is loaded (package 

dependencies) 

Export a package or partial package page 82 

Replicate or copy the contents of a package 

and send (publish) it to other Integration 

Servers 

Disable a package without deleting the 

package 

Enable a package that you previously 

disabled 

Recover services and related files from a 

deleted package 

Archive a copy of the package (such as for a 

backup copy) 

page 78 and 












Creating a Package 


When you want to create a new grouping for services and related files, create a package. 

Packages can store services, specifications, IS document types, output templates, and 

schemas. 

When you create a package, Developer creates a new subdirectory for the package in the 

file system on the machine where the Integration Server is installed. For information 

about the subdirectory and its contents, see the webMethods Integration Server 

Administrator’s Guide. 

Guidelines for Naming Packages 

Keep the following guidelines in mind when naming new packages: 

� Start all package names with an uppercase letter and capitalize the first letter of 

subsequent words (for example, PurchaseOrder). 

� Keep package names short. Use abbreviations instead of full names. For example, 

instead of ProcessPurchaseOrder, use ProcessPO. 

� Make sure the package name describes the functionality and purpose of the services it 

contains. 

� Avoid creating package names with random capitalization (for example, 

cOOLPkgTest). 

� Avoid using articles (for example, “a,” “an,” and “the”) in the package name. For 

example, instead of TestTheService, use TestService. 

� Avoid using the prefix “Wm”. Developer uses the “Wm” prefix for predefined 

packages that contain services, IS document types, and other files. 

To create a package 


2 In the New dialog box, select Package, and then click Next. 

Developer displays the New Package dialog box. 

3 In the Name field, type the name for the new package using any combination of letters, 

numbers, and the underscore character. Click Finish. 

Developer refreshes the Navigation panel and displays the new package. 



Note: Avoid using control characters and special characters like periods (.) in a 

package name. The watt.server.illegalNSChars setting in the server.cnf file (which is 

located in the webMethods6\IntegrationServer\config directory) defines all the 

characters that you cannot use when naming packages. Additionally, the operating 

system on which you run the Integration Server might have specific requirements that 

limit package names. 

Tip! You can quickly create a package beneath the server you are currently working with 

by clicking next to the New button on the toolbar and then clicking Package. Type the 

name of the package and then click OK. 

You can then create a folder beneath the package by clicking next to the New button 

and then clicking Folder. Developer adds the folder beneath the package, with a default 

name of Untitled. 

Viewing Details for a Package 

Double-clicking a package in the Navigation panel expands or collapses the contents of 

that package. To view details for a package in the editor, perform the steps in the 

following procedure. 

To view details for a package 

1 Select the packages whose details you want to view. 


For more information about package details, see “Assigning a Version Number to a 

Package” on page 83, “Viewing the Patch History for a Package” on page 83, and 

“Identifying Package Dependencies” on page 85. 

Optimizing Lock Checking 

If the Developer’s Version Control System (VCS) Integration feature is enabled, Developer 

might exhibit slowdowns, error messages (such as "Server version has changed" and 

"Session already in use"), and may stop responding completely when you expand a large 

element (such as a folder) or a large package in the Navigation panel. This condition 

occurs when Developer queries the Integration Server to check the lock state of each 

element in a package. 


To optimize lock checking 


1 Open the file ..\webMethods6\Developer\config\developer.cnf with 

a text editor. 

2 Add the following properties to the file: 

dev.maxServerLockInfoCalls= 

Defines the maximum number of lock state queries that will be made from Developer 

to Integration Server. The default value is 20. After this maximum is reached, cached 

values are retrieved for each element. These cached values may be inaccurate, but the 

only result is that menu items may be enabled or disabled incorrectly. 

dev.maxLockInfoCalls= 

Defines the maximum number of cached lock states that are retrieved. The default 

value is 100. After this maximum is reached, the last known lock state for each 

remaining element is used. This state may be incorrect, but as above, the only result is 

that menu items may be enabled or disabled incorrectly. 

For example, when a large package is opened (using the default values): Full lock 

status information will be retrieved for the first 20 elements. For elements 21-100, 

cached lock state information will be retrieved. For elements 101 and above, the last 

known lock state will be used. 

3 Save the file. 

4 Shut down and restart Developer. 

Note: The lower the values for these settings, the more the performance will improve. 

Applying a value of zero (0) to these settings will eliminate all lock state queries to the 

server. This may result in some temporarily out-of-sync lock states, but these will be 

updated during normal Developer operations. 

Lock state information is updated as child elements are opened in the Navigation panel. 

Copying a Package to Another Server 

You can copy a package to another Integration Server in one of two ways: 

� From Developer. You can copy a package and its contents to another Integration Server 

from within Developer by performing a copy or a drag-and-drop action. Copying 

packages using either of these methods provides a quick way to share a set of services 

and their supporting files with other developers in a development environment. 

� From Integration Server Administrator. You can also copy a package from within the 

Integration Server Administrator by replicating the package. You can then send, or 

publish, the package to other Integration Servers. Copying packages using this 

method allows you to customize the way in which packages are replicated and 



published. This method is useful for managing releases between development and 

production environments, for deploying releases to partners or customers, or for 

distributing package updates to developers working in large, collaborative 

environments. 

For information about replicating packages and managing releases from within 

Integration Server Administrator, see the webMethods Integration Server Administrator’s 


When copying packages, keep the following points in mind. 

� You can copy a package to a different server only if you are a member of a group 

assigned to the Replicators ACL on the source and destination servers and you are 

logged on to both servers. 

� Before you copy a package that contains elements with unsaved changes, you must 

save the changes. 

� You cannot undo a copy action using the Edit�Undo command. 

� You cannot copy a package to another server if the destination server already contains 

a package with that name. 

Note: Because UNIX directories are case sensitive, Integration Servers running in a 

UNIX environment will allow packages with similar names to reside on the same 

server. For example, you can copy a package named orderProcessing to a server that 

contains a package named OrderProcessing. 

� If you copy a package that depends on other packages to load (that is, contains 

package dependencies), and the required packages are not present on the destination 

server, the package will be copied but it will not be enabled. 

For more information about setting package dependencies, see “Identifying Package 

Dependencies” on page 85. 

For more information about copying elements within a package, see Chapter 2, 

“Managing Elements in the Navigation Panel”. 

To copy a package 

1 Select the package that you want to copy. 

2 On the Edit menu, click Copy. 

3 If the package you want to copy contains elements with unsaved changes, Developer 

alerts you that the package cannot be copied until you save the changes. Click OK to 

close the alert dialog box. Then, save the changes and repeat the copy action. 


4 Select the server where you want to copy the package. 

5 On the Edit menu, click Paste After. 


Tip! You can also copy packages by clicking them and dragging them to their new location. 

Developer retains a copy of the package and its contents on the source server. 

Documenting a Package 

You can communicate the purpose and function of a package and its services to other 

developers by documenting the package. 

To create documentation for a package 

1 Document the package in one or more Web documents (such as HTML pages). Be 

sure to name the home page for the package documentation index.html. The 

index.html file can contain links to the other Web documents for the package. An 

index.html file exists for each package installed by the Integration Server. 

2 Place the documents in the pub subdirectory for the package on the Integration 

Server. 

For example, place the package documentation for a package named 

“PurchaseOrders” in the following directory: 

webMethods6\IntegrationServer\packages\PurchaseOrders\pub 

Tip! An alternate location for package documentation is the 

webMethods6\IntegrationServer\packages\doc directory. Typically, this directory is 

used for reference material such as PDFs that do not need to be published to the Web. 

To access documentation for a package 

� Enter the URL for the package documentation. The URLs for package documentation 

have the following format: 

http://serverName:port/PackageName/DocumentName 

where: 

serverName:port is the name and port address of the Integration Server on which 

the package resides. 


Reloading a Package 


PackageName is the name of the package for which you want documentation. 

DocumentName is the name of the Web document you want to access. If you do 

not specify a DocumentName, the Integration Server 

automatically displays the index.html file. 

Sometimes, you need to reload a package on the server to activate changes that have been 

made to it outside of Developer. You need to reload a package if any of the following 

occurs: 

� A Java service that was compiled using jcode is added to the package. 

� New jar files are added to the package. 

� Any of the configuration files for the package are modified. 

Note: Reloading a package is not the same as refreshing the Navigation panel. When you 

refresh the Navigation panel, webMethods Developer retrieves a fresh copy of the 

contents of all the packages from the memory the Integration Server. When you reload a 

package, the Integration Server removes the existing package information from memory 

and loads new versions of the package and its contents into its memory. 

To reload a package 

1 In the Navigation panel, select the package you want to reload. 

2 On the File menu, click Reload Package. 

Deleting a Package 

When you no longer need the services and files in a package, you can delete the package. 

Deleting a package removes the package and all of its contents from the Navigation panel. 

When you delete a package from Developer, the Integration Server saves a copy of the 

package. If you later want to recover the package and its contents, contact your server 

administrator. Only Integration Server Administrator users can recover a package. For 

more information about recovering packages, see the webMethods Integration Server 



Before you delete a package, make sure that: 


� Other users or other services do not use (depend on) the services, templates, IS 

document types, and schemas in the package. You can use the Find Dependents 

command to identify other services that are dependent on a service in a package that 

you want to delete. For more information, see “Finding Dependents and References” 

on page 63. 

� All elements in the package that you want to delete are unlocked, or locked by you. If 

the package contains elements that are locked by others or system locked, you cannot 

delete the package. 

To delete a package 

1 In the Navigation panel, select the package you want to delete. 


Exporting a Package or Element 

Packages or parts of a package, such as a folder, can be exported to your hard drive so that 

they can be shared with partners or developers. You can install an exported package on 

another server by using the package publishing functionality in the Integration Server 

Administrator. Locking information is not exported. 

To export a package 

1 In the Navigation panel, select the package you want to export. 

2 On the File menu, click Export. Developer displays the Export To dialog box. 

3 Select the location on your hard drive where you want the exported package to reside. 

Click Save. 

This exports the package to a ZIP file and saves it on your hard drive. The ZIP file can 

then be published on another server. 

To export an element 

1 In the Navigation panel, select the folder or element that you want to export. 

2 On the File menu, click Export. Developer displays the Export To dialog box. 

3 Select the location on your hard drive where you want the exported partial package to 

reside. Click Save. 

This exports the folder or element to a ZIP file and saves it on your hard drive. The 

ZIP file can then be unzipped into the ns directory of a package on the server. 


Assigning a Version Number to a Package 


You can assign a version number to a package to identify different versions of the 

package. For example, you might want to assign a new version number to a package when 

you add new services to the package or after you fix bugs in a package. You might find 

assigning version numbers especially helpful if you work in a development environment 

where more than one person makes changes to a package. 

By default, Developer assigns the version number 1.0 to each package that you create. 

Important! When you change the version number of a package, make sure that you update 

the package dependencies for other packages that depend on the earlier version of this 

package. 

Tip! Assign and change package version numbers through Developer only when the 

packages are in a development stage. To avoid difficulties installing package releases, do 

not change version numbers on packages you receive from trading partners, packages to 

which you subscribe, or packages installed with the Integration Server. 

To assign a version number to a package 

1 In the Navigation panel, select the package to which you want to assign a version 

number. 


3 In the editor, click the package’s Settings tab. 

4 In the Package Version field, type the version number you want to assign to the 

package. Be sure to format the version number in one of the following ways: X.X or 

X.X.X (for example, 1.0, 2.1, 2.1.3, or 3.1.2). 

5 On the File menu, click Save to save your changes. 

If the version number you entered does not use one of the formats specified in step 4, 

Developer displays a message stating that the format is not correct. 

Note: You can also use the Integration Server Administrator to assign version numbers to 

packages. For more information, see the webMethods Integration Server Administrator’s 


Viewing the Patch History for a Package 

For each package, Developer tracks and displays the history of installed patches. A patch 

is a partial upgrade, change, or fix to the contents of a package. 


These fields display 

information about the 

currently installed patch... 

...and these fields track 

the patch history for the 

package. 

You might want to check a package’s patch history for the following reasons: 


� To avoid overwriting the installed package with a lower version of the same package. 

� To view the changes that are included in each version of the package. 

� To inform webMethods Customer Care which versions of predefined packages are 

installed on your Integration Server. 

When you open a package in the editor, the package’s Settings tab displays the patch 

history since the last full release of the package. (A full release of a package incorporates 

all previous patches for the package.) 

The Settings tab displays patch history for the package 

Note: With the exception of the Package version field and the fields under Package 

dependencies, the fields on the Settings tab are display-only. 

Note: When the server administrator installs a full release of a package (a release that 

includes all previous patches for the package), the Integration Server removes the existing 

patch history. This helps the server administrator avoid potential confusion about version 

numbers and re-establish a baseline for package version numbers. 


To view patch history for a package 


1 In the Navigation panel, select the package for which you want to view a patch 

history. 


3 In the editor, click the package’s Settings tab and review the fields under Patch history. 

This field... Specifies... 

Name The name of the package. 

Version The version number of the package. A user assigns a version 

number when they create a package release. By default, Developer 

assigns version 1.0 to a new package. 

Build The build number of the package. The build number is a 

generation number that a user assigns to a package each time the 

package is released. For example, a user might release version 1.0 

of the “Finance” package ten times and assign build numbers 

1,2,3…10 to the different releases or builds of the package. 

The Build number is not the same as the Version number. One 

version of a package might have multiple builds. 

Description A brief description of the package written by the user who created 

the package release. 

Time The time at which the package release (patch) was created. 

JVM Number The version of the JVM (Java virtual machine) required to run the 

package. 

Publisher The name of the publishing server that created the package release. 

Patch Number The patch numbers included in this release of the package. 

Identifying Package Dependencies 

If a package needs the services in another package to load before it can load, you must set 

up package dependencies. For example, you should identify package dependencies if a 

startup service for a package invokes a service in another package. The startup service 

cannot execute if the package containing the invoked service has not yet loaded. 

You should also identify package dependencies if Java services in a package need to access 

Java classes contained in another package. 

When you identify a package dependency, you must indicate the version number of the 

package that needs to load first. For example, the “Finance” package might depend on 

version 2.0 of the “FinanceUtil” package. It is possible that the services and elements 



needed by a dependent package are contained in more than one version of the same 

package. For example, the “Finance” package might depend on version 2.0 or later of the 

“FinanceUtil” package. 

Important! If you create new adapter services and adapter notifications, you should save 

them in packages that identify the webMethods AdapterName package as a package 

dependency. 

Important! Other webMethods components might include packages that register new types 

of elements in Developer. You should save instances of these new element types in 

packages that list the registering package as a package dependency. The registering 

package needs to load before your packages so that Developer can recognize instances of 

the new element type. For example, if you create new flat file schemas, you should save 

the flat file schemas in packages that identify the WmFlatFile package as a package 

dependency. 

To identify package dependencies for a package 

1 In the Navigation panel, select the package for which you want to specify package 

dependencies. 



4 Under Package Dependencies, click . 

5 In the Enter Input Values dialog box, enter the following information: 



6 Click OK. 

7 On the File menu, click Save. 

Removing Package Dependencies 


Package The name of the package you want Integration Server to load 

before the package selected in the Navigation panel. 

Version The version number you want Integration Server to load before the 

package selected in the Navigation panel. 

More than one version of the same package might contain the 

services and elements that a dependent package needs the 

Integration Server to load first. You can use an asterisk (*) as a 

wildcard in the version number to indicate that any version 

number greater than or equal to the specified version will satisfy 

the package dependency. For example, to specify version 3.0 or 

later of a package, type 3.* for the version number. To specify 

versions 3.1 or later, type 3.1.* for the version number. 

If any version of the package satisfies the package dependency, 

type *.* as the version number. 

Important! Only one version of a package can be installed at one time. If the available 

version of the package specified in the package dependency is not the correct version, the 

Integration Server does not load the dependent package. The Integration Server writes a 

dependency load error for the dependent package to the server log. 

Important! Make sure that you do not create circular package dependencies. For example, if 

you identify “FinanceUtil” as a dependent package for the “Finance” package, do not 

identify “Finance” as a dependent package for the “FinanceUtil” package. If you create 

circular package dependencies, neither package will load the next time you start the 

Integration Server. 

Use the following procedure to remove a package dependency that is no longer needed. 

For example, to continue the example from page 85, if you delete the service in “Finance” 

that invokes the service in “FinanceUtil,” then you would no longer need a package 

dependency on the “FinanceUtil” package. Another case where you would remove the 

package dependency is if you move the services in the “FinanceUtil” package into the 

“Finance” package. 


To remove a package dependency 


1 In the Navigation panel, select the package for which you want to remove a package 

dependency. 



4 Under Package Dependencies, select the package dependency you want to remove. 

5 Click . 


Assigning Startup, Shutdown, and Replication Services 

You can set up services to automatically execute each time Integration Server loads, 

unloads, or replicates a package. These types of services are called startup, shutdown, or 

replication services. 

What Is a Startup Service? 

A startup service is one that Integration Server automatically executes when it loads a 

package into memory. The server loads a package: 

� At server initialization (if the package is enabled). 

� When someone uses Developer or the Integration Server Administrator to reload a 

package. 

� When someone uses Developer or the Integration Server Administrator to enable a 

package. 

Startup services are useful for generating initialization files or assessing and preparing 

(for example, setting up or cleaning up) the environment before the server loads a 

package. However, you can use a startup service for any purpose. 

Tip! If a startup service invokes a service in another package, make sure to identify the 

other package as a package dependency for the package containing the startup service. 


What Is a Shutdown Service? 


A shutdown service is one that the Integration Server automatically executes when it 

unloads a package from memory. The server unloads a package from memory: 

� At server shutdown or restart. 

� When someone uses the Integration Server Administrator to disable the package. 

� When someone uses the Integration Server Administrator to reload a package before 

it is removed from memory. 

Shutdown services are useful for executing clean-up tasks such as closing files and 

purging temporary data. You could also use them to capture work-in-progress or state 

information before a package unloads. 

What Is a Replication Service? 

A replication service is one that Integration Server automatically executes when it 

prepares to replicate a package. A replication service executes when the Integration Server 

Administrator creates a package release (full release or patch) or creates a package 

archive. 

Replication services provide a way for a package to persist state or configuration 

information so that these are available when the published package is activated on the 

remote server. 

Note: The term replication service does not refer to the services contained in pub.replicator or 

to services that subscribe to replication events (replication event services). 

Guidelines for Assigning Startup, Shutdown, and 

Replication Services 

Keep the following guidelines in mind when assigning startup, shutdown, and replication 

services to packages: 

� When you assign a startup or shutdown service to a package, you can only assign a 

service that resides in the same package. For example, a startup service for the 

“Finance” package must be located in the “Finance” package. 

� When you assign a replication service to a package, you can assign any service from 

any loaded package on Integration Server, including the current package. 



� Because services in a package are not made available to clients until the package’s 

startup services finish executing, you should avoid implementing startup services 

that access busy remote servers. They will delay the availability of other services in 

that package. 

� You can assign one or more startup services to a package; however, you cannot 

specify the order in which the services execute. If you have a series of startup services 

that need to execute in a specific order, create a “wrapper” service that invokes all the 

startup services in the correct order. Designate the “wrapper” service as the startup 

service for the package. 

Assigning Startup, Shutdown, and Replication Services 

Use the following procedure to identify startup, shutdown, and replication services. 

To assign startup, shutdown, and replication services 

1 In the Navigation panel, select the package to which you want to assign startup, 

shutdown, or replication services. 


3 In the editor, click the package’s Startup/Shutdown/Replication Services tab. 

4 To assign a startup service, under Startup services, select the service from the Available 

Services list, and click . 

Repeat this step for each service you want to add as a startup service for the package. 

Note: A service that you just created does not appear in the Available Services list if you 

have not refreshed your session on the server since you created the service. 

5 To add a shutdown service, under Shutdown services, select the service from the 

Available Services list, and click . 

Repeat this step for each service you want to add as a shutdown service for the 

package. 

6 To add a replication service, do the following: 

a Under Replication Services, click . 

b In the Enter Input Values dialog box, in the Service field, do one of the following: 

� Type the service name in the format: folderName:serviceName 

� Click to navigate to and select the service that you want to use as a 

replication service. 


c Click OK. 


d Repeat these steps for each service you want to add as a replication service. 

Removing Startup, Shutdown, and Replication Services 

You might need to remove a startup, shutdown, or replication service if the service is no 

longer needed, has been deleted, or has been incorporated into another service (such as a 

wrapper service). 

Tip! If you remove a startup service that invoked a service in another package and the 

package was identified as a package dependency, make sure you remove the package 

dependency after you remove the startup service. 

To remove startup, shutdown, and replication services 

1 In the Navigation panel, select the package for which you want to remove startup, 

shutdown, or replication services. 


3 In the editor, click the package’s Startup/Shutdown/Replication Services tab. 

4 Do one or more of the following: 

� To remove a startup service, under Startup services, select the service you want to 

remove from Selected services list, and click . 

� To remove a shutdown service, under Shutdown services, select the service you 

want to remove from the Selected services list, and click . 

� To remove a replication service, under Replication services, select the replication 

service you want to remove and click . 




Chapter 4. Locking and Unlocking Elements 

� Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 

� Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

� Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

� Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

� Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 


Basic Concepts 

4. Locking and Unlocking Elements 

In webMethods Developer, you can manage changes to elements during development by 

locking them. This prevents two different users from editing an element at the same time. 

You can lock elements such as flow services, Java services, schemas, and specifications. 

All elements in Developer’s Navigation panel are read-only until you lock them. You can 

edit an element only if you own the lock on the element. However, you can use and run a 

service regardless of its lock status, as long as you have Execute access to the service. For 

details, see Chapter 5, “Assigning and Managing Permissions”. 

This chapter describes local locking on the Integration Server, which is the default locking 

mode of Developer. If you enable Developer’s VCS Integration feature, elements are 

locked and unlocked when you check them out of or into your version control system 

repository. For more information about implementing and using the VCS Integration 

feature, see the webMethods Version Control System Integration Feature Developer’s Guide in 

the ..\webMethods6\Developer\doc\guides directory. 

What Is a Lock? 

A lock on an element prevents another user from editing that element. There are two 

types of locks: user locks and system locks. When an element is locked by you, you have a 

user lock. The element is read-only to all other users on the Integration Server. Another 

user cannot edit the element until you unlock it. 

When an element’s supporting files (node.xml, for example) are marked read-only on the 

Integration Server, the element is system locked. For example, the server administrator has 

the ability to mark an element’s supporting files on the server as read-only, in which case 

they are system locked. To edit the element, you must ask the server administrator to 

remove the system lock (that is, make the element’s files writable), and then you must 

reload the package in which the element resides. 

Important! When an Integration Server has the VCS Integration feature enabled, system 

locking is effectively disabled for elements that are checked into the version control 

system. The VCS Integration feature will override any read/write status changes applied 

manually by a server administrator. 

Elements are shown in the following ways in Developer: 

Element Status Can I edit? How do I gain rights to edit? 

Not locked No Click File�Lock for Edit. 

Locked by you Yes N/A 


Locking Elements 

How Do I Know Who Has an Element Locked? 


Element Status Can I edit? How do I gain rights to edit? 

Locked by another user No Contact the user to unlock. 

Locked by the system No Contact the server 

administrator to unlock. 

On every element in the Navigation panel, you can view the lock status by using the Lock 

Status command. This command provides information about the element such as the 

username of the person who owns the lock and when they locked it. If an element is 

system locked, you can also use the Lock Status command to obtain the names of the server 

files that are read-only on the server. For details, see “Viewing the Status of Locked 

Elements” on page 98 and “Viewing an Element’s Corresponding Server Files” on 

page 103. 

When Do I Lock an Element? 

You lock an element when you want to make changes to the element. For details, see 

“Locking Elements” on page 96. 

When Do I Unlock an Element? 

You unlock an element after making your changes and saving those changes to the server. 

It is important to unlock the elements you are done with so that other users on the server 

can access them. For details, see “Unlocking Elements” on page 100. 

If you want to automatically unlock an element after saving it, you can enable a setting on 

the Options dialog box. For details, see “Automatically Unlocking Elements After Saving” 

on page 104. 

Before you edit an element, you must lock it. This ensures that you are the only person 

working on a particular element at a time, preventing the loss of changes. Elements can 

only be locked by one user at a time. If the element you need is already locked, request 

that the current owner of the lock release it. If the element is system locked, request that 

the server administrator release it by making the corresponding server files writable. 


Locking Elements 


Elements are locked by webMethods username (the name you use to log on to the 

Integration Server). Because of this, it is important that you use a distinct username to log 

on to the server. If you change usernames, you will be unable to edit or unlock items that 

you locked using your old username. 

When locking elements, keep the following points in mind: 

� When you create a new element, it is locked automatically for you. 

� In order to lock an element, you must have Write access rights to it. For details, see 

Chapter 5, “Assigning and Managing Permissions”. 

� When you lock an element, Developer obtains and locks the latest version of the 

element that has been saved on the webMethods Integration Server. 

� Elements generated by a service (including an adapter service) are not locked 

automatically. 

� When you select multiple elements to lock, some elements in the selection may not be 

available to lock because they may be system locked, locked by another user, elements 

to which you do not have Write access, or elements that cannot directly be locked. 

Developer will notify you that these elements cannot be locked and will lock the rest. 

� When you lock an adapter notification, Developer also locks its associated publishable 

document type. You cannot directly lock the publishable document type associated 

with an adapter notification. 

� When you lock a folder or package, you only lock existing, unlocked elements within 

it. Other users can still create new elements in that folder or package. 

Note: Users cannot create Java and C/C++ services in a folder or package while other 

users own the lock on the folder or package. These types of services require that all 

existing Java and C/C++ services in the folder are unlocked and the user has Write 

access to all Java and C/C++ services in the folder. For details, see “Locking Java and 

C/C++ Services” on page 97. 

� When you lock a Java or C/C++ service, Developer locks all other Java or C/C++ 

services within the folder. For details, see “Locking Java and C/C++ Services” on 

page 97. 

� You cannot lock a listener or connection element. 

To lock elements 

1 In the Navigation panel, select the elements that you want to lock. 

2 On the File menu, click Lock for Edit. 



If the elements were successfully locked, a green check mark appears next to their 

icons in the Navigation panel. If one or more of the elements could not be locked (for 

example, if they are system locked, locked by another user, or elements to which you 

do not have Write access), Developer displays a dialog box listing them. For 

information about troubleshooting lock problems, see “Lock/Unlock Problems” on 

page 105. 

Tip! You can also lock an element that is open in the editor by right-clicking the element’s 

tab or title bar and then clicking Lock for Edit. 

Locking Java and C/C++ Services 

When you lock Java and C/C++ services, there are special considerations to keep in mind. 

� Locking and unlocking actions on Java and C/C++ services are folder-wide. All Java and C/C++ 

services in a folder share the same .java and .class files on the Integration Server. 

These files, located in the \code subdirectory of a package, correspond to all services 

(except flow services) in a folder. Therefore, when you lock a Java/C service, all Java/C 

services in that folder are locked. 

For example, if you lock a Java service in a folder A, all Java and C/C++ services in 

folder A are locked by you. Similarly, if another user has locked a Java service in 

folder B, you cannot add, edit, move, or delete any Java or C/C++ services in folder B. 

� Locking actions on Java and C/C++ services are ACL dependent. If you want to lock one or 

more Java or C/C++ services within a folder, you must have Write access to all Java 

and C/C++ services in that folder. This is because Java and C/C++ services within a 

folder share the same .java and .class files. 

� The jcode development environment operates independently of locking. If you use jcode to 

develop Java services, you do not have the locking functionality that is available in the 

Integration Server. When you use jcode, you may compile a service that is locked by 

another user, overwriting that user’s changes to the service. Therefore, if you use 

jcode, do not use the locking features in the Integration Server. 

� Before you save a Java or C/C++ service, multiple corresponding files must be writable on the 

server. A single Java or C/C++ service corresponds to the following files: 

.java 

.class 

.ndf 

.frag (may not be present) 

Before you save a Java or C/C++ service, all of the preceding files must be writable. 

Therefore, make sure that all system locks are removed from those files before saving. 


Locking Templates 


A template can be used with one or more services on the Integration Server. Currently, 

you cannot lock a template as an entity, only the service to which it is attached. Following 

are considerations for working with templates in a cooperative development 

environment. 

� To create or edit a template for a service, you must have the service locked. 

� The template for a service can change without your knowledge. Since a template can be 

attached to one or more services, keep in mind that a shared template can change 

without your knowledge. For example, if your template is attached to a service that 

another user locks and edits, that user can change your template. 

System Locking Elements 

If you are a server administrator, you can system lock an element by using the server’s file 

system to make the element’s supporting server files read-only. If you do not know the 

names of the files that correspond to a particular element, use the Lock Status command. 

For details, see “Viewing an Element’s Corresponding Server Files” on page 103. Usually, 

a system lock is not reflected in webMethods Developer or the Integration Server 

Administrator until you reload the package in which the element resides. 

Important! Before you system lock an element, always verify that it is not locked by a user 

on the Integration Server. If an element becomes system locked while a user is editing it, 

the user will not know until he or she tries to save changes to the element. If this occurs, 

make the element’s corresponding files writable on the server. After this is done, the user 

can save his or her changes to the element. 

Viewing the Status of Locked Elements 

The lock status of an element tells you if an element is available for locking, and if not, 

who owns the lock and when they locked it. You can view the status of a locked element 

to see who owns the lock or you can view a list of all elements for which you own the lock. 

When viewing an element’s lock status, keep the following points in mind: 

� If the element has been system locked since you last reloaded the package, Developer 

will not show the system lock status in the Locking Status dialog box until you reload 

the package. 

� When another user unlocks an element, you must refresh the Navigation panel to 

reflect the updated status. Similarly, when the server administrator removes a system 

lock from an element, you must reload the package in which the element resides to 

reflect the updated status. 


To view lock status for an element 


1 In the Navigation panel, select the element for which you want to view the status. 

2 On the File menu, click Lock Status. The following dialog box appears if the element is 

locked by someone else. A similar dialog appears if the element is system locked or 

locked by you. 

Locking Status dialog box 

To list all elements locked by you 

� On the Tools menu, click My Locked Elements. The My Locked Elements dialog box 

appears. 

My Locked Elements dialog box 

You can unlock individual elements from this dialog box by pressing the CTRL key as you 

click each element and then clicking Unlock. You can unlock all elements by clicking Unlock 

All. For more information about unlocking elements, see “Unlocking Elements” on 

page 100. 


Unlocking Elements 

Copying, Moving, or Deleting Locked Elements 


You can copy a locked element to another folder or package. However, you cannot move, 

rename, or delete an element unless it is locked by you or unlocked. 

After you edit an element and save changes to the server, you should unlock it to make it 

available to other users. There are several ways to unlock elements, depending on 

whether you are a member of the Developers ACL or the Administrators ACL. If you are a 

developer, you can unlock elements in Developer. If you are an administrator, you can 

unlock elements in the Integration Server Administrator as well as in Developer. 

Unlocking Elements Using Developer 

You must explicitly unlock elements. Disconnecting from the server does not unlock your 

element(s), since your locks are maintained from session to session. 

When unlocking elements, keep the following points in mind: 

� When you unlock a single Java or C service, Developer unlocks all other Java or C 

services within the folder. For details, see “Locking Java and C/C++ Services” on 

page 97. 

� If a Java or C service in a folder has unsaved changes, you will not be able to unlock 

other Java or C services within that folder. Save the changes and then unlock the 

services. 

� When you unlock an adapter notification, Developer also unlocks its associated 

publishable document type. You cannot directly unlock the publishable document 

type associated with an adapter notification. 

� You cannot unlock a listener or connection element. 

. 

To unlock elements using Developer 

1 In the Navigation panel, select the elements that you want to unlock. 

Note: Be sure to save changes to the elements before you attempt to unlock them. 

2 On the File menu, click Unlock. 

3 If the elements you want to unlock contain unsaved changes, Developer alerts you 

that the elements cannot be unlocked until you save the changes. Click OK to close the 

alert dialog box. Then, save the changes and repeat the unlock action. 



4 If one of the elements you selected to unlock is a publishable document type 

associated with an adapter notification, and you did not also select the adapter 

notification, Developer alerts you that the elements cannot be unlocked. Click OK to 

close the alert dialog box. Then, reselect the elements (including the appropriate 

adapter notifications) and repeat the unlock action. 

The Navigation panel refreshes and the green check mark next to the element disappears. 

Tip! You can also unlock elements using the following techniques: 

- To unlock an element that is open in the editor, right-click the element’s tab or title 

bar and then click Unlock. 

- To unlock all elements to which you own the lock, use the Tools�My Locked Elements 

command. 

Unlocking an Element Using the Integration Server 

Administrator 

Important! Be cautious when you remove user locks to prevent a user from losing changes. 

If you unlock an element while a user is editing it, the user will not know until he or she 

tries to save changes to the element and the action fails. Always confirm with the user 

before removing his or her lock on an element. 

To unlock an element using the Integration Server Administrator 

1 In the Integration Server Administrator, under Packages, click Management. 

2 Click View Locked Elements. The following screen appears, showing all elements that 

have user locks and system locks. 

Locked Elements screen 

“localhost” means the machine 

on which the server is running 


3 Click Unlock Elements. The following screen appears. 

Unlock Selected Elements screen 


� Locked by System. Lists elements whose corresponding files are marked read-only 

on the server file system. You cannot remove a system lock via the Server 

Administrator. On the server’s file system, you must make the element’s files 

writable and reload the package. For details, see “Unlocking a System Locked 

Element” on page 103. 

� Locked by Current User. Lists elements that are locked by you, the server 

administrator (or the username with which you logged on to the Integration 

Server Administrator). Before you unlock an item, make sure that you have saved 

all changes to the server. 

� Locked by Other Users. Lists elements that are locked by other users on the server. 

Before you remove a user’s lock, make sure that the user has saved all changes to 

the server. If not, the user will lose all changes that they made to the element since 

they last saved it to the server. 

4 Select the elements that you want to unlock (after informing users if necessary) and 

click Unlock Selected Elements. 

Developers using webMethods Developer should refresh their Navigation panel to 

update their view of the lock status of all elements. 

Important! If you receive a “failed to unlock” message, it means that the server files for a 

locked element were deleted from the server. Use the Sync to Name Space command to 

update the Integration Server Administrator’s view of locked elements. 


Unlocking a System Locked Element 


If you are a server administrator, you can remove a system lock from an element using the 

server’s file system. After you remove the system lock, you must reload the package in 

which the element resides to reflect the element’s updated status. If you use Developer, 

you must refresh the Navigation panel (after the package is reloaded) to reflect the 

element’s updated status. 

To remove a system lock from an element 

1 If you do not know the names of the server files that correspond to the element, use 

the Lock Status command in Developer. For details, see “Viewing an Element’s 

Corresponding Server Files” on page 103. 

2 On the server’s file system, remove the read-only properties from the files that 

correspond to the element to make the files writable. 

3 Reload the package on the Integration Server that contains the element. The updated 

status is reflected in the Integration Server Administrator. Refresh the Navigation 

panel in Developer to view the updated status. 

Important! If you accidentally applied a system lock to an element that was already locked 

by another user, remove the system lock but DO NOT have the user reload the package in 

webMethods Developer. (Reloading the package in Developer will discard their edits.) 

The user can then save the element without losing the changes he or she made to it while 

you had the element system-locked. 

Viewing an Element’s Corresponding Server Files 

You can view the names of the server files associated with every webMethods element. 

This is convenient when an element is system locked and you need to convey the 

element’s file names to the server administrator. 

To view server files for an element 

1 In the Navigation panel, select the elements for which you want to view the server file 

names. 

2 On the File menu, click Lock Status. 

The following dialog box shows the server files associated with a flow service named 

ApplyCreditMemo. These server files are system locked (that is, they are not writable on 

the server). 


Viewing server files for element ‘ApplyCreditMemo’ 


Note: After a server administrator removes a system lock from an element, you must 

reload the package in which the element resides to reflect the unlocked status. 

Automatically Unlocking Elements After Saving 

You can choose to automatically unlock flow services, IS document types, and 

specifications after you save changes to them. This prevents you from forgetting to unlock 

them; however, it may not be the best option if you save periodically while editing an 

element. 

Important! When an Integration Server has the VCS Integration feature enabled, the 

Automatically unlock upon save option must be disabled. 

To automatically unlock flow services, IS document types, and specifications after saving 

To 

1 On the Tools menu, click Options. The Options dialog box appears. 

2 Click General. 

3 Under Navigation Panel, select the Automatically unlock upon save check box. 

4 Click OK. 


Troubleshooting 


This section addresses common problems that may arise when implementing cooperative 

development with webMethods components. 

Lock/Unlock Problems 

The Lock for Edit and Unlock commands are disabled. 

Possible causes are: 

� The Integration Server to which you are connected may have the 

watt.server.ns.lockingMode property configured to “no locking” or “system 

locking only.” For details, contact your server administrator. 

� You have selected multiple elements to lock or unlock and your selection contains of 

one or more of the following: 

� A server 

� A folder or package and its contents 

� A package and any other element 

� An adapter notification record 

When I try to lock an element, I get an exception message. 

The element may be locked by someone else, system-locked (marked read-only on the 

server), or you may not have Write access. Refresh the Navigation panel. If a lock is not 

shown but you still cannot lock the element, reload the package. In addition, make sure 

that you are a member of the ACL assigned for Write access to the element by checking 

the element’s Permissions property in the Properties panel. 

I can’t unlock a Java or C service. 

If there is another Java or C service that is locked by another user or system locked in the 

same folder, then you cannot unlock any Java or C services in that folder. This is because 

those services share the same .java and .class files on the Integration Server. 

I can’t unlock elements since I changed my username. 

You can only unlock elements that you have locked with your current username for the 

session. If you have changed usernames, log back in to the server with your old username 

and then unlock the elements. 

If the administrator has deleted your username, contact him or her to unlock the elements 

on the server. You can assist the administrator by using the Lock Status command to 

identify the names of the system-locked files on the server that need to be unlocked. 

Another user unlocked an element, but it still shows as locked in my Navigation panel. 

If it is a Java or C service, reload the package in the Navigation panel. If it is any other 

element, use the Refresh command to refresh the Navigation panel. 



I receive an “element failed to unlock” message when I try to unlock elements in the Integration Server 

Administrator. 

This indicates that the server files for the locked element were deleted from the server. 

You need to update the Integration Server Administrator’s list of unlocked elements by 

clicking Sync to Name Space on the Unlock Selected Elements screen. The Sync to Name 

Space command runs automatically when the server is started or restarted. 

Package Management Problems 

I can’t preserve locking information when I replicate and publish a package. 

This is expected behavior and is part of the feature’s design. You can, however, preserve 

system locks (read-only file attributes). 

When I disable a package, it does not preserve locking information. 

This is expected behavior and prevents conflicts if another package with the same folder 

and element names gets installed. 

Save Problems 

When I try to save an element that I have locked, I get an exception message. 

During the time that you had the lock, the element became system-locked, its ACL status 

changed, or a server administrator removed your lock and another user locked the 

element. If the exception message indicates that a file is read-only, then one or all of the 

files that pertain to that element on the server are system-locked. Contact your 

administrator to remove the system lock. After this is done, you can save the element and 

your changes will be incorporated. 

If the exception message indicates that you cannot perform the action without ACL 

privileges, then the ACL assigned to the element has been changed to an ACL in which 

you are not an Allowed user. To preserve your changes to the element, contact your server 

administrator to: 

1 Remove your lock on the element. 

2 Lock the element. 

3 Edit the ACL assigned for Write access to the element, to give you access. 

4 Unlock the element. 

You can then save your changes to the element. 

When I try to save a template, I get an error message. 

The template file on the server is read-only. Contact your server administrator to make the 

file writable. 


Other Problems 


I can’t create a new Java or C service. 

Another Java or C service is locked in the folder in which you want to create the new 

service, or you do not have Write access to all Java or C services in the folder. All of them 

must be unlocked or locked by you and you must have Write access to add a new Java or 

C service to the same folder. See “Lock/Unlock Problems” on page 105. 

I can’t delete a package. 

One of the elements in that package is system-locked (read-only) or locked by another 

user. Contact your administrator or contact the user who has the element locked in the 

package. 

The webMethods Integration Server went down while I was locking or unlocking an element. 

The action may or may not have completed, depending on the exact moment at which the 

server ceased action. When the server is back up, restore your session and look at the 

current status of the element. 

Frequently Asked Questions 

What is the difference between a system-locked element and a read-only element? 

None. “System lock” is a term used to denote an element that has read-only files on the 

webMethods Integration Server. The server administrator usually applies system locks to 

files (makes them read-only). 

Can I select multiple elements to lock or unlock in the Navigation panel simultaneously? 

Yes, you can select multiple elements to lock or unlock in the Navigation panel, as long as 

your selection does not contain the following: 

� A server 

� A folder or package and its contents 

� A package and any other element 

� An adapter notification record 

You can also lock or unlock all elements in a package or folder that have not been 

previously locked/unlocked by right-clicking the package or folder and selecting Lock for 

Edit (to lock) or Unlock (to unlock). 

I only save elements after I’m completely done. Remembering to unlock elements after saving them is 

tedious. Is there a shortcut for this task? 

Yes. For the specific procedure, see “Automatically Unlocking Elements After Saving” on 

page 104. 

Where is the lock information stored (such as names of elements that are locked, when they were 

locked, etc.)? 

The information is stored in the webMethods Repository version 2. For information on the 

Repository, see the webMethods Integration Server Clustering Guide. 



Important! It is not recommended that you use Cooperative Development functionality in a 

Remote Repository configuration. Locking information for elements could be 

inadvertently shared with another Integration Server sharing the Remote Repository. 

Also, if the Remote Repository Server goes down or a connection is lost, development will 

be stalled until the Remote Repository Server is back online. Use the local webMethods 

Repository while developing to eliminate these Cooperative Development problems. 

Should I archive derived files? 

Generally, you should not archive derived files such as the .class file that is generated 

when you compile a Java service. 

What happens to the locks on elements when I replicate a package? 

Locking information is not preserved when you replicate and publish a package. This is 

expected behavior and is part of the feature’s design. You can, however, preserve system 

locks (read-only file attributes). 


Chapter 5. Assigning and Managing Permissions 

� Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 

� Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 

� Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

� How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 

� Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 



5. Assigning and Managing Permissions 

In addition to controlling access to elements on an individual user basis using locking, 

you can also control access by groups of users using access control lists (ACLs). Typically 

created by a system administrator, ACLs allow you to restrict access on a broader level. 

For example, if you have a production package and a development package on the 

webMethods Integration Server, you can restrict access to the production package to users 

in an Administrators ACL, and restrict access to the development package to users in a 

Developers ACL. 

Within ACLs, you can also assign different levels of access, depending on the access that 

you want different groups of users to have. For example, you may want a “Tester” ACL to 

only have Read and Execute access to elements. Or, you may want a “Contractor” ACL 

that denies List access to sensitive packages on the webMethods Integration Server, so 

that contractors never see them in webMethods Developer. 

What Is an ACL? 

An ACL controls access to packages, folders, and other elements (such as services, IS 

document types, and specifications) at the group level. An ACL identifies groups of users 

that are allowed to access an element (Allowed Groups) and/or groups that are not 

allowed to access an element (Denied Groups). When identifying Allowed Groups and 

Denied Groups, you select from groups that you have defined previously. 

There are four different kinds of access: List, Read, Write, and Execute. 

� List controls whether a user sees the existence of an element and its metadata; that is, 

its input and output, settings, and ACL permissions. The element will be displayed on 

screens in the Developer and the Integration Server Administrator. 

� Read controls whether a user can view the source code and metadata of an element. 

� Write controls whether a user can update an element. This access also controls whether 

a user can lock, rename, or delete an element or assign an ACL to it. 

� Execute controls whether a user can execute a service. 

For more details about these types of access, see the webMethods Integration Server 


What Happens When a Client Runs a Service with ACLs? 

When a client requests that webMethods Integration Server invoke a service, the server 

checks the ACL assigned to the service. If the client is a member of an allowed group and 

is not a member of a denied group, the server executes the service. If the client is not a 

member of an allowed group, the server denies the request to invoke the service and stops 

executing. 



By default, when a client requests a service, webMethods Integration Server checks only 

the ACL of the externally invoked service (the service requested directly by the client). 

The server does not check the ACLs of any of the internally invoked services (those 

services invoked by the externally invoked service). However, you can set up the security 

settings for a service so that webMethods Integration Server checks the ACL assigned to 

the service every time it is invoked, whether directly by a client or by another service. For 

details, see “The Permissions Properties” on page 114. 

The following diagram illustrates the points at which ACL checking occurs when a client 

requests a service. 

ACL checking when a client requests a service 

Stage Description 

1 

2 

Client 

1 

Purch:SubmitPO 


INVOKE Purch:LogPO 

INVOKE Purch:CreditAuth 

INVOKE Purch:SendPO 


Purch:LogPO 

Purch:CreditAuth 

Purch:SendPO 

The client (such as another application or a DSP) requests the Purch:SubmitPO 

service on the local webMethods Integration Server. webMethods Integration 

Server checks the ACL of the Purch:SubmitPO service (the externally invoked 

service). The server executes the service only if the client is invoking the 

service on the behalf of a user that is a member of an allowed group and is not 

a member of a denied group for the ACL assigned to the service. 

The Purch:SubmitPO service invokes the Purch:LogPO service. Because the 

Purch:LogPO service is invoked by the externally invoked service and is located 

on the same server as the externally invoked service, webMethods Integration 

Server considers the Purch:LogPO service to be internally invoked. 

Consequently, the server does not check the ACL of the Purch:LogPO service 

before executing it. 

webMethods Developer User’s Guide Version 6.5, Service Pack 3 � � � 111 

2 

3 

4


3 

4 

Am I Required to Use ACLs? 


The Purch:SubmitPO service invokes the Purch:CreditAuth service. Like the 

Purch:LogPO service, webMethods Integration Server considers the 

Purch:CreditAuth service to be an internally invoked service. Consequently, the 

server does not check the ACL of the Purch:CreditAuth service before executing it. 

The Purch:SubmitPO service invokes the Purch:SendPO service. Like the 

Purch:LogPO and Purch:CreditAuth services, webMethods Integration Server 

considers the Purch:SendPO service to be an internally invoked service. The 

server does not check the ACL of the Purch:SendPO service before executing it. 

Note: If the security settings for the Purch:LogPO, Purch:CreditAuth, or Purch:SendPO services 

specify that ACL checking occurs every time the service is invoked (Enforce execute ACL 

option is set to Always), webMethods Integration Server would perform ACL checking 

when the externally invoked service (Purch:SubmitPO) invoked these services. For more 

information about requiring ACL checking, see “Assigning ACLs to Elements” on 

page 113. 

Note: Any service that the Purch:SubmitPO flow service invokes could also be invoked 

directly by the client. For example, if the client directly invokes the Purch:SendPO service, 

the server checks the ACL of the Purch:SendPO service. If the client is invoking the service 

on the behalf of a user that is a member of an allowed group and not a member of a denied 

group, then the server executes the Purch:SendPO service. 

No. However, there are default ACL settings for elements shipped with the Integration 

Server and default settings for new elements that you create. For details on default ACLs, 

see the webMethods Integration Server Administrator’s Guide. 

How Do I Create an ACL? 

You create ACLs using the Integration Server Administrator. For details, see the 



Assigning ACLs to Elements 

To 


You can assign an ACL to a package, folder, services, and other elements in the 

Navigation panel. Assigning an ACL restricts or allows access to an element for a group of 

users. You can assign only one ACL per element. 

You cannot assign an ACL to an element for List, Read, or Write access unless you are a 

member of that ACL. For example, if you want to allow DevTeam1 to edit the ProcessPO 

service, you must be a member of the DevTeam1 ACL. That is, your username must be a 

member of a group that is in the Allowed list of the DevTeam1 ACL. 

To assign an ACL to a package or folder 

1 Make sure that the ACL you want to assign exists on the Integration Server. If not, 

create the ACL in the Integration Server Administrator. For details, see the 


2 In the Navigation panel, click the package or folder to which you want to assign an 

ACL. 


4 In the editor, click the title bar of the package or folder to give it the focus. 

5 In the Permissions category of the Properties panel, select the ACLs that you want to 

assign for each level of access. For details, see “The Permissions Properties” on 

page 114. 

Important! For List, Read, and Write access, you can only assign ACLs of which you are 

a member. If you cannot assign an ACL to an element for List, Read, or Write access, 

you probably are not a member of a user group in the Allowed list of that ACL. To 

verify, use the Tools�ACL Information command. To obtain access to an ACL, contact 

your server administrator. 

6 Save the element. If an error message appears, check to make sure that you are a 

member of each ACL that you assigned to the element. 

To assign an ACL to other elements in the Navigation panel 

1 Make sure that the ACL you want to assign exists on the Integration Server. If not, 

create the ACL in the Integration Server Administrator. For details, see the 


2 Open the element to which you want to assign an ACL. 

3 In the Permissions category of the Properties panel, select the ACLs that you want to 

assign for each level of access. For details, see “The Permissions Properties” on 

page 114. 



Important! For List, Read, and Write access, you can only assign ACLs of which you are 

a member. If you cannot assign an ACL to an element for List, Read, or Write access, 

you probably are not a member of a user group in the Allowed list of that ACL. To 

verify, use the Tools�ACL Information command. To obtain access to an ACL, contact 

your server administrator. 

4 Save the element. If an error message appears, check to make sure that you are a 

member of each ACL that you assigned to the element. 

The Permissions Properties 

You assign an ACL to an element in the Permissions category of the Properties panel. 

Depending on the element you select, certain access levels are displayed. For example, for 

a package, you can only set List access. For details about the different levels of access 

available for elements, see the webMethods Integration Server Administrator’s Guide. 

The ACLs assigned to an element are mutually exclusive; that is, an element can have 

different ACLs assigned for each level of access. For example, the following element has 

the Developers ACL assigned for Read access and the Administrators ACL assigned for 

Write access. 

Permissions properties for a flow service 

Field / Button Description 

An element can have different 

ACLs assigned for each level 

of access. 

List ACL Users in the Allowed list of this assigned ACL can see that the element 

exists and view the element’s metadata (input, output, etc.). 

Read ACL Users in the Allowed list of this assigned ACL can view the source 

code and metadata of the element. 

Write ACL Users in the Allowed list of this assigned ACL can lock, edit, rename, 

and delete the element. 

Execute ACL Users in the Allowed list of this assigned ACL can execute the service. 

This level of access only applies to services. 


Field / Button Description 

Enforce 

execute ACL 

ACLs and Inheritance 


� When top-level service only. The Integration Server performs ACL 

checking against the service when it is directly invoked from a 

client or DSP. For example, suppose a client invokes the OrderParts 

service on server A. After checking port access, server A checks the 

Execute ACL assigned to OrderParts to make sure the requesting 

user is allowed to run the service. It does not check the Execute 

ACL when other services invoke OrderParts. 

� Always. The Integration Server performs ACL checking against the 

service when it is directly invoked from a client as well as when it 

is invoked from other services. For example, suppose the OrderParts 

service is invoked from a browser, as well as by the ProcessOrder 

and AddToDatabase services. If Always is set on OrderParts, the server 

performs ACL checking on OrderParts three times (once when it is 

invoked from the browser and twice when it is invoked by 

ProcessOrder and AddToDatabase). 

Note: You can view the users and groups that compose the ACLs on the Integration Server 

to which you are connected by using the Tools�ACL Information command. This 

information is read only; to edit ACLs, users, and groups, use the Integration Server 

Administrator. 

When you assign an ACL to a folder, it affects the subfolders and services in the folder. 

The subfolders and services that do not have an assigned ACL inherit the ACLs that you 

assign to the folder. (Subfolders and services with an assigned ACL are not affected by the 

ACL assigned to the folder.) When a subfolder or service inherits the ACL of a folder, 

“inherited” is displayed next to the ACL in the List, Read, Write, or Execute fields in the 

Permissions category of the Properties panel. 

When you remove an ACL from a service or subfolder, the service or subfolder inherits 

the ACL assigned to the folder in which the service or subfolder is located. When you 

remove the ACL assigned to the top-level folder (the uppermost folder in a package), 

webMethods Integration Server applies the default ACL to the folder and its contents for 

which an ACL is not specified. (The default ACL restricts access to a service to any user 

with a valid username and password for the webMethods Integration Server.) 


Default ACLs and Inheritance 


If the element is a top-level folder, its default ACL is that specified by a configuration file, 

not by its parent (the package). If the element is a subfolder, it shares its default ACL 

settings with other folders at the same level in the folder hierarchy. For details about 

inheritance, as well as the default ACLs that are installed with the webMethods 

Integration Server, see the webMethods Integration Server Administrator’s Guide. 

Note: An element can inherit access from all elements except a package. 

Viewing ACL Information on a Server 

You can view the users and groups that make up the ACLs on a server by using the 

Tools�ACL Information command. The ACL Information dialog box lists the ACLs 

contained on the Integration Server to which you are connected. This information is read 

only; to edit ACLs, users, and groups, use the Integration Server Administrator. 

ACL Information dialog box for a Server 

The Default ACL... 

...denies access to members 

of the Anonymous group... 

...and allows access to 

members of all other groups. 


Field Description 

How ACLs Affect Other Developer Features 

ACLs and Locking 


ACLs The ACLs defined on the Integration Server to which you are 

connected. These include the default ACLs that were installed 

with the server. 

User Group 

Association for 

‘[ACL]’ 

Resulting Users for 

‘[ACL]’ 

� Allowed. The user group(s) that have been explicitly allowed to 

access the packages, folders, services, or other elements 

associated with this ACL. 

� Denied. The user group(s) that have been explicitly denied 

access to the packages, folders, services, or other elements 

associated with this ACL. 

The names of users that the ACL authorizes, given the current 

settings in the Allowed and Denied lists. The server builds this list by 

looking at the groups to which each user belongs and comparing 

that to the groups to which the ACL allows or denies access. For 

details on how the server determines access, see the webMethods 

Integration Server Administrator’s Guide. 

As explained previously, locking allows you to control access at the individual user level, 

while ACLs allow you to control access by groups of users. Following are guidelines to 

keep in mind as you use ACLs with locking: 

� To lock an element, you must be the member of the ACL that is assigned for Write 

access to that element. 

� To lock a Java or C service within a folder, you must be the member of the ACL that is 

assigned for Write access for all Java or C services in that folder. This is because 

locking and unlocking actions for Java/C services are at the folder level. For details, 

see the Chapter 4, “Locking and Unlocking Elements”. 

� To edit ACL permissions for an element, you must lock the element (except for 

packages and folders, which cannot be locked). 

Note: When an Integration Server has the VCS Integration feature enabled, an element is 

locked when it is checked out of the version control system. With the appropriate ACL 

permissions, you are able to check out (lock) and check in (unlock) elements, folders and 

packages. 


ACLs and Testing/Debugging Services 

Keep the following in mind when you test and debug services: 


� To step or trace through a top-level service, you must have Execute, Read, and List 

access to the service. 

� To step or trace through all the services within a top-level service, you must have 

Execute, List, and Read access to all services invoked by the top-level service. If you 

do not have access to services invoked by the top-level service, Developer “steps 

over” those services. (The Integration Server performs ACL checking for a child 

service when the Enforce execute ACL property for the service is set to Always.) 

Developer executes the top-level service and continues to the next flow step. 

Developer does not step into or trace into the top-level service. 

� To test a service by sending an XML file to a service, you must have Read access to the 

service. 

� To set a breakpoint in a service, you must have Read access to the service. 

ACLs and Creating, Viewing, and Deleting Elements 

Keep the following guidelines in mind when you create, view, or delete elements: 

� To create or paste an element, you must have Write access to its parent folder. If you 

are not a member of the ACL assigned for Write access to the folder, contact your 

server administrator. 

� To copy an element, you must have Read access to it and Write access to its parent 

folder. 

� To rename or delete an element, you must have Write access to it and its parent folder. 

� To copy a package, you must be a member of a group assigned to the Replicators 

ACL. 

� When you create a folder and assign an ACL to it, any elements that you create within 

that folder inherit its ACL, until you explicitly set the ACL to something else. For 

details about inheritance, see the webMethods Integration Server Administrator’s Guide. 

� You may not see all of the elements on the Integration Server in the Navigation panel 

because you may not have List access to all of them. You can only see those elements 

to which you have at least List access. 


Troubleshooting 


I receive a “Cannot perform operation without Write ACL privileges” message when I try to create an 

element. 

You are not a member of the ACL assigned to the folder in which you want to save the 

element. To verify, check the Permissions category of the Properties panel. If you had 

previously been able to save the element, the ACL settings may have changed on the 

server since you last saved it. See “Troubleshooting” on page 105 in Chapter 4, “Locking 

and Unlocking Elements”. 

I receive an “element already exists” message when I try to create an element. 

There may be an element with the same name on the Integration Server, but you may not 

be able to see it because you do not have List access to it. Try a different element name, or 

contact your server administrator. 

I can’t assign an ACL to an element. 

Make sure that you have locked the element and that you are a member of the List, Read, 

or Write ACL that you want to assign. To verify, use the Tools�ACL Information command. 

I can’t see the source of a flow or Java service. However, I can see the input and output. 

You do not have Read access to the service. Contact your server administrator to obtain 

access. 

I receive an exception when I try to lock an element. 

The element may be locked by someone else, system locked (marked read only on the 

server), or you may not have Write access. Refresh the Navigation panel. If a lock is not 

shown but you still cannot lock the element, reload the package. In addition, make sure 

that you are a member of the ACL assigned for Write access to the element. To do so, click 

the Permissions category of the Properties panel. 

I receive an error when I run a command on the Test menu. 

You must have a minimum of Read access to trace or step through a service. If you don’t 

have Read access to the service when you are tracing, tracing into, stepping through, or 

stepping into a service, you will receive an error message. 

If you do have Read access to a service but you do not have Read access to a service it 

invokes, Developer “steps over” the invoked service but does not display an error 

message. 

You must also have Read access to a service to set a breakpoint in the service or send an 

XML document to the service. 

I receive an exception when I try to go to a referenced service from the pipeline. 

You do not have List access to the referenced service. Contact your server administrator. 

I receive a “Couldn’t find in Navigation panel” message when I try to find a service in the Navigation 

panel. However, I know it is on the Integration Server. 

If you do not see the service listed in the Navigation panel, you probably do not have List 

access to that service. Contact your server administrator. 



I can’t copy and paste a Java service. 

Check to make sure that you have Write access to all Java services in the folder into which 

you want to paste the service, as well as Write access to the folder itself. 


Chapter 6. Building Flow Services 


� A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 

� Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

� Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

� Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 

� Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 

� Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

� Assigning Universal Names to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 

� Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 

� Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 



Client application invokes 

Purch:SubmitPO... 

6. Building Flow Services 

To successfully build a flow service, you should understand the following basic concepts 

and terms. 

What Is a Flow Service? 

A flow service is a service that is written in the webMethods flow language. This simple yet 

powerful language lets you encapsulate a sequence of services within a single service and 

manage the flow of data among them. For example, you might create a flow service that 

takes a purchase order from a buyer and executes the following series of services before 

submitting it to an internal ordering system: 

1 Gets a purchase order submitted by a buyer 

2 Logs the order in an audit-trail file 

3 Performs a credit check 

4 Posts the order to the ordering system 

Flow services encapsulate other services 


INVOKE Purch:GetOrders 

INVOKE Purch:LogOrder 


INVOKE Purch:PostPO 

...which performs a sequence 

of four services 

Any service can be invoked within a flow (including other flow services). For instance, a 

flow might invoke a service that you create, any of the built-in services provided by 

webMethods, and/or services from a webMethods add-on product such as the 

webMethods JDBC Adapter. 

You create flow services using Developer. They are saved in XML files on webMethods 


Important! Although flow services are written as XML files, they are maintained in a format 

that can only be created and understood by Developer. You cannot create or edit a flow 

service with a text editor. 


1 

2 

3 

4

A LOOP step 

repeats a set of 

flow steps 

A BRANCH step 

selects a specified flow 

step for execution 

What Is a Flow Step? 


A flow service contains flow steps. A flow step is a basic unit of work (expressed in the 

webMethods flow language) that webMethods Integration Server interprets and executes 

at run time. The webMethods flow language provides flow steps that invoke services and 

flow steps that let you edit data in the pipeline. 

webMethods’ flow language also provides a set of control steps that allow you to direct the 

execution of a flow service at run time. The control steps allow you to: 

� Conditionally execute a specified sequence based on a field value. 

� Retry a specified sequence until it succeeds. 

� Repeat a specified sequence (loop) for each element in an array field. 

In the following flow service, control steps have been inserted to loop through a subset of 

the flow service and branch to one of two services in the last step of the loop. 

Control steps are used to direct the execution of a flow 


INVOKE Purch:GetOrders 

LOOP PurchaseOrders 

INVOKE Purch:LogOrder 


BRANCH AuthOK 

INVOKE Purch:PostPO 

INVOKE Purch:BouncePO 

A flow service can contain the following types of flow steps: 

Invocation Steps 

INVOKE 

Executes a specified service. For more information about this 

step, see “The INVOKE Step” on page 165. 


Data-Handling Steps 

MAP 

Control Steps 

BRANCH 

LOOP 

REPEAT 

SEQUENCE 

EXIT 


See Appendix A, “webMethods Flow Steps” for a detailed description of each type of flow 

step provided by the webMethods flow language. For information about building each 

type of flow step, see Chapter 7, “Inserting Flow Steps”. 

What Is the Pipeline? 

Performs specified editing operations on the pipeline (such as 

mapping variables in the pipeline, adding variables to the 

pipeline, and dropping variables from the pipeline). For more 

information about this step, see “The MAP Step” on page 192. 

Executes a specified flow step based on the value of a specified 

variable in the pipeline. For more information about this step, 

see “The BRANCH Step” on page 168. 

Executes a set of flow steps once for each element in a 

specified array. For more information about this step, see “The 

LOOP Step” on page 186. 

Re-executes a set of flow steps up to a specified number of 

times based on the successful or non-successful completion of 

the set. For more information about this step, see “The 

REPEAT Step” on page 179. 

Groups a set of flow steps into a series. The SEQUENCE step is 

implicit in most flow services (that is, the steps in a flow 

service are treated as a series). However, at times it is 

necessary to explicitly group a subset of flow steps using 

SEQUENCE so that they can be treated as a unit. For more 

information about this flow step, see “The SEQUENCE Step” 

on page 185. 

Controls the execution of a flow step (for example, abort an 

entire flow service from within a series of deeply nested steps, 

throw an exception without writing a Java service, or exit a 

LOOP or REPEAT without throwing an exception). For more 

information about this step, see “The EXIT Step” on page 190. 

The pipeline is the general term used to refer to the data structure in which input and 

output values are maintained for a flow service. It allows services in the flow to share 

data. 

The pipeline starts with the input to the flow service and collects inputs and outputs from 

subsequent services in the flow. When a service in the flow executes, it has access to all 

data in the pipeline at that point. 


Services in a flow 

get their input from 

and place their 

output in the 

pipeline. 

The pipeline holds the input and output for a flow service 

INVOKE Purch:LogPO 

Flow Service The Pipeline 


INVOKE Purch:ConvertDate 

INVOKE Purch:SendPO 

output 

output 

output 

output 

ONum:46-77135 

Name:Kings Sport 

Phone:201-887-1544 

TNum:128824993554 

Acct:128824993554 

Total:5732.78 

Qty:20 

AuthNum:TW99123554 

Date:04/04/99 

Item:PK8801-NS 

OrderDate:19990404 

Ship:UPS Ground 

Terms:30N 

Freight:65.00 

Status:Received 


When you build a flow service, you use Developer to specify how information in the 

pipeline is mapped to and from services in the flow. 

What Are Input and Output Parameters? 

Input and output parameters are the names and types of fields that the service requires as 

input and generates as output. For example, a service that takes two string values—an 

account number (AcctNum) and a dollar amount (OrderTotal)—as input and produces an 

authorization code (AuthCode) as output, has the following input and output parameters: 

Input and output parameters define the fields that the service requires as input and generates as output 


input 

input 

input 

input 

Input Output 

Name Data Type Name Data Type 

AcctNum String AuthCode String 

OrderTotal String

A Process Overview 


Part of the process of creating a service is declaring its input and output parameters (that 

is, explicitly specifying the fields it expects as input and produces as output). 

Building a flow service is a process that involves the following basic stages: 

Stage 1 

Stage 2 

Stage 3 

Stage 4 

Stage 5 

Stage 6 

Stage 7 

Creating a new service on webMethods Integration Server. During this stage, 

you create the new service on the webMethods Integration Server where 

you will do your development and testing. For information about this 

stage, see “Creating a New Flow Service” which follows. 

Inserting flow steps into the new service. During this stage, you specify the 

work that you want the service to perform by adding flow steps to the 

service. For information about this stage, see Chapter 7, “Inserting Flow 

Steps”. 

Declaring the input and output parameters of the service. During this stage, you 

define the service’s inputs and outputs. For information about this stage, 

see “Declaring Input and Output Parameters for a Service” on page 129. 

Mapping pipeline data. During this stage, you route input and output 

variables between services that are invoked in the flow. For information 

about this stage, see Chapter 8, “Mapping Data in a Flow Service”. 

Specifying the run-time parameters. During this stage, you assign parameters 

that configure the run-time environment for this service. For information 

about this stage, see “Specifying Run-Time Parameters” on page 137. 

Formatting service output. During this stage you can create an output 

template to format the service output. For information about this stage, 

see “Assigning an Output Template to a Service” on page 134 or refer to 

the Dynamic Server Pages and Output Templates Developer’s Guide. 

Testing and debugging. During this stage you can use the tools provided by 

Developer to test and debug your flow service. For information about 

this stage, see Chapter 11, “Testing and Debugging Services”. 

The remaining sections in this chapter and the following chapters provide detailed 

information about each stage. 


Creating a New Flow Service 


The first step you take when you build a flow service is to create a new service on the 

webMethods Integration Server where you do your development. 

Package and Folder Requirements 

Before you create a new flow service, you must: 

� Make sure the package in which you want to create the flow service already exists. If the 

package does not already exist, create it using Developer. For more information about 

creating a package, see “Creating a Package” on page 76. 

� Make sure the folder in which you want to create the service already exists and that you have 

Write ACL access to it. If the folder does not already exist, create it using Developer. For 

information about creating folders, see “Creating New Elements” on page 45. For 

information about ACL permissions, see Chapter 5, “Assigning and Managing 

Permissions”. 

Once the package and folder are in place, you use the File�New command to start the 

process of creating a new service. For more information, see “Creating New Elements” on 

page 45. 

Using the Default Logic Options 

The wizard that creates a new flow service gives you the option of starting with an empty 

flow (one that contains no predefined flow steps) or starting with a service that contains a 

set of default logic for extracting information from an HTML or XML document (a 

common flow-service function). 

If you are building a flow service that extracts data from an HTML or XML document, you 

can select an option to automatically generate the logic (that is, the set of flow steps) that 

will get data from a specified document, rather than building this logic manually. 

Use this option... To... 

Empty Flow Generate a flow service that does not have any logic. 

Load and Query an 

HTML Page 

Automatically generate a flow service that invokes the loadXMLNode 

service (which gets a document from a URL that you specify) and 

the queryXMLNode service (which extracts a specified set of elements 

from the document returned by loadXMLNode). 

For additional information about the loadXMLNode and queryXMLNode 

services, see the XML Services Developer’s Guide. 


Use this option... To... 

Receive an XML 

Document 

Inserting Flow Steps 


Automatically generate a service that receives an XML node as 

input. If you specify the format by providing a DTD or XML 

Schema definition, webMethods Developer maps the incoming 

document to its corresponding IS document type structure. 

Important! The flow steps produced by these options are no different than those produced 

by manually inserting INVOKE loadXMLNode and INVOKE queryXMLNode steps in a flow 

service. After Developer inserts the set of default steps into your flow service, you can edit 

the default steps and insert additional steps just as you would any ordinary flow service. 

Flow steps call previously built services and direct the flow of data within a flow service. 

You can insert flow steps into a flow service using the buttons at the top of the editor. For 

more information, see Chapter 7, “Inserting Flow Steps”. 

To insert a/an... Click this button... 

INVOKE step 

MAP step 

BRANCH step 

LOOP step 

REPEAT step 

SEQUENCE step 

EXIT step 


Declaring Input and Output Parameters for a Service 


Input and output parameters are the names and data types of the fields that a service 

expects as input and generates as output. Some systems refer to input and output 

parameters as “imports” and “exports.” These parameters are also collectively referred to 

as a signature. 

You declare input and output parameters for all types of services: flow services, Java 

services, and services written in other supported programming languages. 

Although you are not required to declare input and output parameters for a service (the 

Integration Server will execute a service regardless of whether it has a specification or 

not), there are good reasons to do so: 

� Declaring parameters makes the service’s input and outputs visible to Developer. Without 

declared input and output parameters, you cannot: 

� Link data to and/or from the service using Developer’s Pipeline tab. 

� Assign default input values to the service on the Pipeline tab. 

� Validate the input and output values of the service at run time. 

� Test the service in Developer and enter initial input values. 

� Generate skeleton code for invoking the service from a client. 

� Declaring parameters makes the input and output requirements of your service known to other 

developers who may want to call your service from their programs. 

For these reasons, we strongly recommend that you make it a practice to declare input 

and output parameters for every service that you create. 

Supported Data Types 

webMethods Developer supports several data types for use in services. Each data type 

supported by Developer corresponds to a Java data type and has an associated icon. When 

working in the editor, you can determine the data type for a field by looking at the icon 

next to the field name. 

For information about these data types and the editor icons that represent them, see 

Appendix C, “Supported Data Types”. 


Specifying Input Parameters 


When you define the input parameters for a flow service, keep the following points in 

mind: 

� Specify all inputs that a calling program must supply to this flow service. For example, if a 

flow service invokes two other services, one that takes a field called AcctNum and 

another that takes OrderNum, you must define both AcctNum and OrderNum as input 

parameters for the flow service. 

Note: The purpose of declaring input parameters is to define the inputs that a calling 

program or client must provide when it invokes this flow service. You do not need to 

declare inputs that are obtained from within the flow itself. For example, if the input 

for one service in the flow is derived from the output of another service in the flow, 

you do not need to declare that field as an input parameter. 

� When possible, use variable names that match the names used by the services in the flow. 

Variables with the same name are automatically linked to one another in the pipeline. 

(Remember that variable names are case sensitive.) If you use the same variable 

names used by flow’s constituent services, you reduce the amount of manual data 

mapping that needs to be done. When you specify names that do not match the ones 

used by the constituent services, you must use the Pipeline tab to manually link them 

to one another. For information about the Pipeline tab, see “What Does the Pipeline Tab 

Contain?” on page 196. 

� Avoid using multiple inputs that have the same name. Although Developer permits you to 

declare multiple input parameters with the same name, the fields may not be 

processed correctly within the service or by services that invoke this service. 

� Make sure the variables match the data types of the variables they represent in the flow. For 

example, if a service in the flow expects a document list called LineItems, define that 

input variable as a document list. Or, if a service expects a Date object called 

EmploymentDate, define that input variable as an Object and apply the java.util.Date 

object constraint to it. For a complete description of the data types supported by 

Developer, see Appendix C, “Supported Data Types”. 

� Declared input variables appear automatically as inputs in the pipeline. When you select the 

first service or MAP step in the flow, the declared inputs appear under Pipeline In. 

Important! If you edit a cached service by changing the inputs (not the pipeline), you must 

reset the server cache. If you do not reset it, the old cached input parameters will be used 

at run time. To reset the service cache from Developer, select the service and then click the 

Reset button next to Reset Cache in the Properties panel. To reset the service cache from 

Integration Server Administrator, select Service Usage under Server in the Navigation 

panel. Select the name of the service and an information screen for that service appears. 

Click Reset Server Cache. 



Note: If you intend to use this service in a trigger to process published documents, the 

input signature for this service needs to contain a document reference to the publishable 

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

the publishable document type (for example, folder.subfolder:PublishableDocumentTypeName). 

You can copy and paste the fully qualified document type name from the Navigation 

panel to the document reference field on the Input/Output tab. For more information about 

creating triggers and publishable document types, see the Publish-Subscribe Developer’s 


Specifying Output Parameters 

On the output side of the Input/Output tab you specify the variables that you want the flow 

to return to the calling program or client. The guidelines for defining the output 

parameters are similar to those for defining input parameters: 

� Specify all of the output variables that you want this flow service to return to the calling 

program or client. 

� Make sure the names of output variables match the names used by the services that produce 

them. Like input variables, if you do not specify names that match the ones produced 

by the flow’s constituent services, you must use the Pipeline tab to manually link them 

to one another. For information about the Pipeline tab, see “What Does the Pipeline Tab 

Contain?” on page 196. 

� Avoid using multiple outputs that have the same name. Although Developer permits you to 

declare multiple output parameters with the same name, the fields may not be 

processed correctly within the service or by services that invoke this service. 

� Make sure the variables match the data types of the variables they represent in the flow. For 

example, if a service produces a String called AuthorizationCode, make sure you define 

that variable as a String. Or, if a service produces a Long object called EmployeeID, 

define that output variable as an Object and apply the java.lang.Long object constraint 

to it. For a complete description of the data types supported by a service, see 

Appendix C, “Supported Data Types”. 

� Declared output variables appear automatically as outputs in the pipeline. When you select the 

last service or MAP step in a flow, the declared output variables appear under Pipeline 

Out. 

Completing the Input/Output Tab 

You declare the input and output parameters for a service using the Input/Output tab. On 

the left side of this tab, you define the variables that the service requires as input. On the 

right side, you define the variables the service returns to the client or calling program. 


Define the flow 

service’s input 

parameters 

on this side... 

Input/Output tab 

...and output 

parameters on this 

side. 


For a flow service, the input side describes the initial contents of the pipeline. In other 

words, it specifies the variables that this flow service expects to find in the pipeline at run 

time. The output side identifies the variables produced by the flow service and returned 

to the pipeline. 

You can complete the Input/Output tab in the following ways: 

� Reference a specification. A specification defines a set of service inputs and outputs. You 

can use a specification to define input and output parameters for multiple services. 

When you assign a specification to a service, you cannot add, delete, or modify the 

declared variables using the service’s Input/Output tab. 

� Reference an IS document type. You can use an IS document type to define the input or 

output parameters for a service. When you assign an IS document type to the Input or 

Output side of the Input/Output tab, you cannot add, modify, or delete the variables on 

that half of the tab. 

You insert a reference to an IS document type in one of three ways: 

� By typing the fully qualified name of the IS document type in the Input or Output 

field 

� By clicking to select an IS document type from a list 

� By dragging an IS document type on the same server from the Navigation panel 

to the box below the Validate input or Validate output check boxes 

With the first two methods, the variables within the IS document type become the 

input or output signature for the service. You cannot add, modify, or delete the 

variables on that half of the tab. With the third method, the IS document type 

reference becomes the top-level document in the signature. You cannot modify or 

delete the variables that are contained within the referenced IS document type but 

you can add other variables to that half of the tab. 



� Manually insert input and output variables. Use to specify the data type and name 

for each input and output variable for the service. 

To declare input and output parameters for a service 

1 Open the service for which you want to declare input and output parameters. 

2 In the editor, click the Input/Output tab for that service. 

3 If you want to reference a specification, do the following: 

a In the Specification Reference field, type the specification’s name or click to 

select it from a list. For more information about creating specifications, see 

“Declaring Input and Output Parameters for a Service” on page 129. 

b Skip the rest of this procedure. 

Important! When a specification is assigned to a service, you cannot add, delete, or 

modify the declared variables using the service’s Input/Output tab. 

4 If you want to reference an IS document type for the input or output parameters of the 

service, do the following: 

a In the Input or Output field (depending on which half of the specification you want 

to assign the IS document type to), type the IS document type name or click to 

select it from a list. You can also drag an IS document type from the Navigation 

panel to the box below the Validate input or Validate output check boxes. 

b If you assigned an IS document type to both the Input and Output sides of the 

Input/Output tab, skip the rest of this procedure. Otherwise, continue to the next 

step to specify the variables in the other half of the tab. 

Important! When an IS document type is assigned to the Input or Output side, you cannot 

add, delete, or modify the declared variables on that half of the Input/Output tab. 

5 For each input or output variable that you want to define, do the following: 

a Select the half of the Input/Output tab (Input or Output) where you want to define the 

variable by clicking anywhere in that half’s large white text box. 

b Click on the toolbar and select the type of variable that you want to define. 

c Type the name of the variable and press ENTER. 



d With the variable selected, set variable properties and apply constraints in the 

Properties panel (optional). 

e If the variable is a document or a document list, repeat steps b–d to define and set 

the properties and constraints for each of its members. Use to indent each 

member beneath the document or document list variable. 

6 If you want to enter any notes or comments about the input and output parameters, 

type your comments on the Comments tab. 

Assigning an Output Template to a Service 

An output template is a Web document, such as an HTML page, embedded with special 

codes (tags) that webMethods Integration Server processes. These tags instruct 

webMethods Integration Server to perform a specific action and substitute the result of 

that action in the Web document. Typically, you use tags in output templates to insert 

service output values in Web documents returned to clients. 

Output templates are used most frequently to customize the HTML page that a service 

returns to a browser-based application. However, they can also be used to generate an 

XML document or any other formatted string. For example, you may have a service that 

retrieves a record from a relational database and uses an output template to format it as an 

XML document or a comma-delimited record before returning it to the requester. 

Note: Output templates are optional. If a service has an output template assigned to it, the 

server automatically applies the template to the results of the service (that is, the contents 

of the pipeline) whenever that service is invoked by an HTTP client. If a service does not 

have an output template, the server simply returns the results of the service in the body of 

an HTML document, formatted as a two-column table. 

When using output templates, keep in mind that: 

� A service can have at most one output template assigned to it at a time (you can 

dynamically change the output template assignment at run time, however). 

� You can assign the same output template to more than one service. 

� If you assign an existing output template to a service, the output template must reside 

in the webMethods6\IntegrationServer\packages\packageName\templates directory, 

where packageName is the package in which the service is located. 

� You can reference one output template from within another. 

� You can specify the encoding in which to save the template (for example, SJIS, a type 

of Japanese encoding). The Integration Server is optimized for the UTF-8 encoding. 

You should not change this setting unless you are sure that you want to use another 

encoding. 


To assign an output template to a service 

1 Open the service to which you want to assign an output template. 

2 In the editor, click the service’s title bar to give the service the focus. 


3 In the Output template category of the Properties panel, do one of the following to 

update the Name field: 

� If you want to assign a new output template to the service, type the name of the 

new output template or accept the system default output template name of 

FolderName_ServiceName. 

� If you want to assign an existing output template to the service, type the file name 

of the existing output template. You do not need to include the path information 

or the file name extension. 

Important! Make sure the existing output template resides in the 

webMethods6\IntegrationServer\packages\packageName\templates directory, 

where packageName is the same package in which the service is located. 

4 In the Type list, do one of the following to specify the format for the output template: 

To... Select... 

Assign an HTML output template to the service html 

Assign an XML output template to the service xml 

Assign a WML output template to the service wml 

Assign an HDML output template to the service hdml 

Note: The Type you select determines the extension for the output template file (*.html, 

*.xml, *.wml, or *.hdml). In cases where the output is returned to a Web browser, the 

Type also determines the value of the HTTP “Content-Type” header field (for example, 

“text/html,” “text/xml,” “text/vnd.wap.wml,” or “text/x-hdml“). 


� If you assigned a new output template to the service, click New to create the 

output template. 

� If you assigned an existing output template to the service and you want to edit the 

template, click Edit. 

Select the encoding used to create the template file and click OK. (By default, 

Developer uses UTF-8 to create output template files.) 



6 In the template dialog box, create or edit the output template by typing HTML, XML, 

WML, or HDML content, and/or by inserting template tags. For more information 

about creating an output template, see the Dynamic Server Pages and Output Templates 

Developer’s Guide. 

7 In the File Encoding list, select the encoding in which you want the template file saved. 

The encoding is used by the Integration Server to send the template to the browser 

and to interpret data posted in the resulting page in the browser. 

The default encoding is Unicode (UTF8). You should not change this setting unless 

you are sure that you wish to use another encoding. The Integration Server is 

optimized for the UTF-8 encoding. The encoding you choose also applies to any 

localized (translated) versions of the template that you may create, so you should 

choose a character encoding that supports all of the languages for which you will 

create localized templates. For details, see the Dynamic Server Pages and Output 

Templates Developer’s Guide. 

If you do change this setting, make sure that your XML or HTML file contains the 

proper encoding or META tag for the encoding you use, as this may affect the browser 

or parser performance outside the Integration Server. 

Note: The File Encoding you select limits the characters that you can use in your 

template (including the data inserted into your template using %VALUE% 

statements) to those in the character set of the encoding you choose. It also limits any 

translated versions of the templates to the same character set. Generally it is a good 

idea to use the UTF-8 (Unicode) encoding, since Unicode supports nearly all of the 

characters in all of the world's languages. You will not lose any data if you choose to 

save your template in UTF-8; any data entered into a form will be properly 

interpreted by the Integration Server. 

8 Click Save. 

Important! After editing a template in Developer, do not edit it outside of Developer. This 

will affect the interpretation of the encoding settings and may result in characters being 

lost or misinterpreted. 


Specifying Run-Time Parameters 


As a developer of a service, you can use the Properties panel to specify the following 

service parameters: 

� State of a service. You can maintain whether or not you want the server to treat it as a 

“stateless” service at run time. 

� Caching of service results. You can cache elements to reduce memory usage in 

Developer. For details, see “To cache elements” on page 70. 

� Execution locale of a service. You can set the type of locale in which the Integration 

Server executes at run time. 

Important! The Runtime properties on the Properties panel should only be set by someone 

who is thoroughly familiar with the structure and operation of the selected service. 

Improper use of these options can lead to a service failure at run time and/or the return of 

invalid data to the client program. 

Maintaining the State of a Service 

When a remote client opens a session on a webMethods Integration Server, the server 

automatically builds a session object for that client. The server uses this object to maintain 

specific information about the client requesting the service, such as user name and 

password. The server maintains the session object for the duration of the session (that is, 

until the client program explicitly closes the session on the server or the session times out 

due to client inactivity). 

When you develop services in a language such as Java, C/C++, or Visual Basic, you can use 

the “put” method to write information to the session object. You might do this to store 

information that a sequence of services needs to maintain a connection to an external 

system. 

A service that is an atomic unit of work (that is, one that is wholly self contained and not 

part of a multi-service transaction to an external system) does not to need to have its 

session object maintained when it is finished executing. For performance reasons, you 

may want to configure these types of services to run in “stateless” mode. Services that run 

in “stateless” mode use fewer resources and do not consume a licensed seat on 


Important! Do not use the stateless option unless you are certain that the service operates as 

an atomic unit of work. If you are unsure, set the Stateless property in the Runtime category 

to False. 


To configure a service’s run-time state 

1 Open the service that you want to configure. 



3 In the Runtime category of the Properties panel, do one of the following to set the 

Stateless property: 

� If the service is a self-contained, atomic unit of work and does not need access to 

state information, select True. The server will remove the client session 

immediately after the service executes, and no session information will be 

maintained for the service. 

� If the service is part of a multi-service transaction or if you are unsure of its state 

requirements, select False. The server will build and maintain a session object for 

this service. 

Configuring a Service’s Use of Cache 

Caching is an optimization feature that can improve the performance of stateless services. 

When you enable caching for a service, webMethods Integration Server saves the entire 

contents of the pipeline after invoking the service in a local cache for the period of time 

that you specify. The pipeline includes the output fields explicitly defined in the cached 

service, as well as any output fields produced by earlier services in the flow. When the 

server receives subsequent requests for a service with the same set of input values, it returns 

the cached result to the client rather than invoking the service again. 

Caching can significantly improve response time of services. For example, services that 

retrieve information from busy data sources such as high-traffic commercial Web servers 

could benefit from caching. The server can cache the results for flows, Java services, and 

C/C++ services. 

Note: Caching is only available for data that can be written to the repository server. Since 

nodes cannot be written to the repository, they cannot be cached. 

Types of Services to Cache 

While caching service results can improve performance, not all services should be cached. 

You should never cache services if the cached results might be incorrect for subsequent 

invocations or if the service performs tasks that must be executed each time the service is 

invoked. This section describes guidelines for you to consider when determining whether 

to cache the results for a service. 


Services Suited for Caching 


� Services that require no state information. If a service does not depend on state 

information from an earlier transaction in the client’s session, you can cache its results. 

� Services that retrieve data from data sources that are updated infrequently. Services whose 

sources are updated on a daily, weekly, or monthly basis are good candidates for 

caching. 

� Services that are invoked frequently with the same set of inputs. If a service is frequently 

invoked by clients using the same input values, it is beneficial to cache the results. 

Services that You Should Not Cache 

� Services that perform required processing. Some services contain processing that must be 

processed each time a client invokes it. For example, if a service contains accounting 

logic to perform charge back and you cache the service results, the server does not 

execute the service, so the service does not perform charge back for the subsequent 

invocations of the service. 

� Services that require state information. Do not cache services that require state 

information from an earlier transaction, particularly information that identifies the 

client that invoked it. For example, you do not want to cache a service that produced a 

price list for office equipment if the prices in the list vary depending on the client who 

initially connects to the data source. 

� Services that retrieve information from frequently updated sources. If a service retrieves data 

from a data source that is updated frequently, the cached results can become 

outdated. Do not cache services that retrieve information from sources that are 

updated in real time or near real time, such as stock quote systems or transactional 

databases. 

� Services that are invoked with unique inputs. If a service handles a large number of unique 

inputs and very few repeated requests, you will gain little by caching its results. You 

might even degrade server performance by quickly consuming large amounts of 

memory. 

Controlling a Service’s Use of Cache 

You use the properties on the Properties panel to enable caching and to configure the way 

in which you want it to operate with the selected service. You use these settings to strike 

the right balance between data currency and memory usage. To gauge the effectiveness of 

your cache settings, you can monitor its performance by viewing service statistics with the 

Integration Server Administrator and then adjusting your caching values accordingly. 

Note: If you do not have administrator privileges on your webMethods Integration Server, 

work with your server administrator to monitor and evaluate your service’s use of cache. 



Important! If you edit a cached service by changing the inputs (not the pipeline), you must 

reset the server cache. If you do not reset it, the old cached input parameters will be used 

at run time. To reset the service cache from Developer, select the service and then click the 

Reset button next to Reset Cache in the Properties panel. To reset the service cache from 

Integration Server Administrator, select Service Usage under Server in the Navigation 

panel. Select the name of the service and an information screen for that service appears. 

Click Reset Server Cache. 

Specifying the Duration of a Cached Result 

The server maintains results in cache for the period of time you specify in the Cache expire 

property on the Properties panel. The expiration timer begins when the server initially 

caches a result, and it expires when the time you specify elapses. (The server does not reset 

the expiration timer each time it satisfies a service request with a cached result.) The 

minimum cache expiration time is one minute. 

Note: The cache may not be refreshed at the exact time specified in Cache expire. It may vary 

from 0 to 15 seconds, according to the cache sweeper thread. For details, see the 

watt.server.cache.flushMins setting in webMethods Integration Server. 

Using the Prefetch Option 

You use the Prefetch property to specify whether or not you want the server to 

automatically refresh the cache for this service when it expires. If you set Prefetch to True, 

the server automatically re-executes the service (using the same set of inputs as before) to 

update its results in cache. This action also resets the cache expiration timer. 

Important! Use Prefetch carefully. Overuse can quickly exhaust the memory available for 

cache. 

Important! Do not use Prefetch with Java or C/C++ services that invoke access-controlled 

services. Such services will fail during prefetch because the embedded service will be 

invoked without the proper access privileges. To avoid this problem, enable Prefetch on 

the invoked services rather than on the Java or C/C++ services that call them. 

When you enable Prefetch, you must also set the Prefetch activation property to specify 

when the server should initiate a prefetch. This setting specifies the minimum number of 

times a cached result must be accessed (hit) in order for the server to prefetch results. If 

the server retrieves the cached results fewer times than specified in the Prefetch activation 

property, the server will not prefetch the service results when the cache expires. 



Note: The cache may not be refreshed at the exact time the last hit fulfills the Prefetch 

activation requirement. It may vary from 0 to 15 seconds, according to the cache sweeper 

thread. For details, see the watt.server.cache.flushMins setting in webMethods 


To enable caching of pipeline contents after a service is invoked 

1 Open the service for which you want to configure caching. 


3 In the Runtime category of the Properties panel, set Cache results to True. 

4 In the Cache expire field, type an integer representing the length of time (in minutes) 

that you want the results for this service to be available in cache. 

5 If you want to use prefetch, do the following: 

a Set Prefetch to True. 

b In the Prefetch activation property, specify the minimum number of hits needed to 

activate the use of prefetch. 

Specifying the Execution Locale 

When you create a service, you can set the locale property to indicate the locale policy in 

which the service executes at run time. The locale policy of a service refers to the language, 

regional, or cultural settings of a specific target market (the end user). Each locale consists 

of five sections: language, extended language, script, region, and variant. 

Locales can influence the following: 

� String display of numeric values and date/time values 

� Parsing of dates and numbers from strings 

� Default currency (pounds, Euros, dollars) 

� Default measuring system (metric or customary) 

� Default system resources (such as fonts, character encoding, etc.) 

� Collation (sorting) of lists 

� User interface/content language 

The Integration Server recognizes the following locale policies at run time: 

� Server locale uses its default JVM locale. 

� User locale uses the client locale. 


� Root locale uses neutral or POSIX locale. 

� Null locale uses no locale policy. 


You can also enable the Integration Server to recognize custom locales. By default, the 

service uses the null locale. That is, it uses no locale policy. 

To specify the execution locale of a service 

1 Open the service that you want to configure. 


3 In the Runtime category of the Properties panel, do one of the following to specify the 

Execution Locale property: 


[$default] Default Runtime Locale Use the server’s default JVM locale. 

[$user] Default User Locale Use the client locale. 

[$null] No Locale Policy Use no locale policy. 

[root locale] Use the neutral or POSIX locale. 

[] Use a specific locale. 

Open locale editor... Define a custom locale. 

4 If you selected Open locale editor, complete the following in the Define Custom Locale 

dialog box. 

In this field... Do the following... 

Language Select one of the ISO 639 codes that represent the 

language. (2- or 3-letter codes) 

Extended Language For future release. 

Script Optional. Select one of the 4-letter script codes in the 

ISO 15924 registry. 

Region Optional. Select one of the ISO 3166-2 country 

codes. 

IANA Variant Optional. Add or remove a variant code registered 

by the IANA. 

5 Click OK. The Integration Server will execute the service in the specified locale. 


Configuring Service Retry 


When building a service, you can configure the service to retry automatically if the service 

fails because of an ISRuntimeException. An ISRuntimeException occurs when the service 

catches and wraps a transient error, and then re-throws it as an ISRuntimeException. A 

transient error is an error that arises from a temporary condition that might be resolved or 

restored quickly, such as the unavailability of a resource due to network issues or failure 

to connect to a database. The service might execute successfully if the Integration Server 

waits a short interval of time and then retries the service. 

To configure a service to retry, you specify the maximum retry attempts and the retry 

interval. The maximum retry attempts indicate how many attempts the Integration Server 

makes to re-execute the service when it ends because of an ISRuntimeException. The retry 

interval indicates the length of time (in milliseconds) that the Integration Server waits 

between execution attempts. 

At run time, when a service throws an ISRuntimeException, the Integration Server waits 

the length of the retry interval and then re-executes the service using the original input 

pipeline passed to the service. The Integration Server continues to retry the service until 

the service executes successfully or the Integration Server makes the maximum number of 

retry attempts. If the service throws an ISRuntimeException during the final retry 

attempt, the Integration Server treats the last failure as a service error. The service ends 

with a service exception. 

Integration Server generates the following journal log message between retry attempts: 

[ISS.0014.0031V3] Service serviceName failed with ISRuntimeException. 

Retry x of y will begin in retryInterval milliseconds. 

Note: If service auditing is also configured for the service, the 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 the Integration Server makes the 

maximum retry attempts and the service still fails, the final audit log entry for the service 

will have a status of “Failed” and will display the actual error message. 

About the Maximum Retry Period 

The Integration Server uses the same server thread for the initial service execution and the 

subsequent retry attempts. The Integration Server returns the thread to the server thread 

pool only when the service executes successfully or the retry attempts are exhausted. To 

prevent the execution and re-execution of a single service from monopolizing a server 

thread for a long time, the Integration Server enforces a maximum retry period when you 

configure service retry properties. The maximum retry period indicates the total amount 

of time that can elapse if the Integration Server makes the maximum retry attempts. By 

default, the maximum retry period is 15,000 milliseconds (15 seconds). 

When you configure service retry, the Integration Server verifies that the retry period for 

that service will not exceed the maximum retry period. The Integration Server determines 



the retry period for the service by multiplying the maximum retry attempts by the retry 

interval. If this value exceeds the maximum retry period, Developer displays an error 

indicating that either the maximum attempts or the retry interval needs to be modified. 

Note: The watt.server.invoke.maxRetryPeriod server parameter specifies the 

maximum retry period. To change the maximum retry period, change the value of this 

parameter. 

Setting Service Retry Properties 

When configuring service retry, keep the following points in mind: 

� You can configure retry attempts for flow services, Java services, and C services only. 

� Only top-level services can be retried. That is, a service can be retried only when it is 

invoked directly by a client request. The service cannot be retried when it is invoked 

by another service (that is, when it is a nested service). 

� If a service is invoked by a trigger (that is, the service is functioning as a trigger 

service), the Integration Server uses the trigger retry properties instead of the service 

retry properties. 

� Unlike triggers, you cannot configure a service to retry until successful. 

� To catch a transient error and re-throw it as an ISRuntimeException, the service must 

do one of the following: 

� If the service is a flow service, the service must invoke 

pub.flow:throwExceptionForRetry. For more information about the 

pub.flow:throwExceptionForRetry, see the webMethods Integration Server Built-In 

Services Reference. 

� If the 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 webMethods Integration 

Server Java API Reference for the com.wm.app.b2b.server.ISRuntimeException 

class. 

� The service retry period must be less than the maximum retry period. For more 

information, see “About the Maximum Retry Period” on page 143. 

To configure service retry 

1 Open the service for which you want to configure service retry. 




3 Under the Retry on ISRuntimeException category of the Properties panel, in the Max 

attempts property, specify the number of times the Integration Server should attempt 

to re-execute the service. The default is 0, which indicates that the Integration Server 

does not attempt to re-execute the service. 

4 In the Retry interval property, specify the number of milliseconds the Integration Server 

should wait between retry attempts. The default is 0 milliseconds, which indicates 

that the Integration Server re-executes the service immediately. 


Tip! You can invoke the pub.flow:getRetryCount service to retrieve the current retry count and 

the maximum specified retry attempts. For more information about this service, see the 

webMethods Integration Server Built-In Services Reference. For more information about 

building a service that retries, see “Configuring Service Retry” on page 143. 

Assigning Universal Names to Services 

Every service on a webMethods Integration Server has a universal name in addition to its 

regular webMethods name. A universal name is a unique public identifier that external 

protocols (such as SOAP) use to reference a service on a webMethods Integration Server. 

A universal name has two parts: a namespace name and a local name. 

� The namespace name is a qualifier that distinguishes a webMethods service from 

other resources on the Internet. For example, there might be many resources with the 

name AcctInfo. A namespace name distinguishes one AcctInfo resource from another by 

specifying the name of the collection to which it belongs, similar to the way in which a 

state or province name serves to distinguish cities with the same name (for example, 

Springfield, Illinois, versus Springfield, Ontario). 

Like namespaces in XML, the namespace portion of a universal name is expressed as a 

URI. This notation assures uniqueness, because URIs are based on globally unique 

domain names. 

The namespace portion of the universal name can consist of any combination of 

characters that form a valid absolute URI (relative URIs are not supported). For 

example, the following are all valid namespace names: 

http://www.gsx.com 

http://www.gsx.com/gl/journals 

http://www.ugmed.ch/résumè 

For a complete description of what makes up a valid URI, see RFC 2396 Uniform 

Resource Identifiers (URI): Generic Syntax at http://www.ietf.org/rfc/rfc2396.txt. 

� The local name uniquely identifies a service within the collection encompassed by a 

particular namespace. Many webMethods users use a service’s unqualified name as 



its local name. Under this scheme, a service named gl.journals:closeGL would have a 

local name of closeGL. 

Local names follow the same construction rules as NCNames in XML. Basically, a 

local name can be composed of any combination of letters, digits, or the following 

symbols: 

. (period) 

- (dash) 

_(underscore) 

Additionally, the local name must begin with a letter or an underscore. The following 

are examples of valid local names: 

addCustOrder 

authorize_Level1 

générent 

For specific rules relating to NCNames, see the “NCName” definition in the 

Namespaces in XML specification at http://www.w3.org/TR/1999/REC-xml-names- 

19990114. 

A universal name can be either an explicit or an implicit universal name. 

� An explicit universal name is a universal name that you assign to a service by specifying 

both a namespace name and a local name in the Properties panel. 

� An implicit universal name is automatically derived from the name of the service itself, 

and it acts as the universal name when an explicit universal name has not been 

specified. The server derives an implicit name as follows: 

� The namespace name is the literal string http://localhost/ followed by the fully 

qualified name of the folder in which the service resides on the Integration Server. 

� The local name is the unqualified name of the service. 

For details on universal names, see the SOAP Developer’s Guide. 

Note: The server normalizes universal names according to Unicode Normalization Form C, 

as recommended by the Character Model, SOAP, and XML standards. This ensures that 

names containing non-ASCII characters (particularly those with accented or combining 

characters) are represented in a standard way. 

For information about normalization, see http://www.unicode.org/reports/tr15/ (Unicode 

Standard Annex #15) and http://www.w3.org/TR/charmod/ (Character Model for the 

World-Wide Web). 


To assign, edit, or view a universal name 

1 Open the service whose universal name you want to assign, edit, or view. 



3 If you want to assign or edit the service’s universal name, specify the following in the 

Universal Name category of the Properties panel: 


Namespace name The URI that will be used to qualify the name of this service. 

You must specify a valid absolute URI. 

Local name A name that uniquely identifies the service within the 

collection encompassed by Namespace name. The name can be 

composed of any combination of letters, digits, or the period 

(.), dash (-) and underscore (_) characters. Additionally, it must 

begin with a letter or the underscore character. 


1 Open the service whose universal name you want to delete. 


3 In the Universal Name category of the Properties panel, clear the settings in the 

Namespace name and Local name fields. 


Note: Many webMethods users use the unqualified portion of 

the service name as the local name. 

Note: If you move a service, or a folder containing a service, Developer retains the service’s 

explicit universal name. If you copy a service, or a folder containing a service, Developer 

does not retain the service’s explicit universal name. 

To delete a universal name 


Configuring Service Auditing 

Specifies if a service 

generates audit data. 

Specifies when to 

include the pipeline in 

the audit log. 


Service auditing is a feature in the Integration Server that you can use to track which 

services executed, when services started and completed, and whether services succeeded 

or failed. You perform service auditing by analyzing the data stored in the audit log. The 

audit log can contain entries for service start, service end, and service failure. The audit 

log can also contain a copy of the input pipeline used to invoke the service. At run time, 

services generate audit data at predefined points. The Integration Server captures the 

generated audit data and stores it in the audit log. If the audit log is a database, you can 

reinvoke services using the webMethods Monitor. 

Note: When the Integration Server logs an entry for a service, the log entry contains the 

identify of the server that executed the service. The server ID in the log entry always uses 

the Integration Server primary port, even if a service is executed using another 

(non-primary) Integration Server port. 

Each service has a set of auditing properties located in the Audit category on the service’s 

Properties panel. These properties determine when a service generates audit data and 

what data is stored in the audit log. For each service, you can decide: 

� Whether the service should generate audit data during execution. 

� The points during service execution when the service should generate audit data to be 

saved in the audit log. 

� Whether to include a copy of the service input pipeline in the audit log. 

Audit properties for a service 

Specifies when a 

service generates audit 

data during execution. 

Keep in mind that generating audit data can impact performance. The Integration Server 

uses the network to send the audit data to the audit log and uses memory to actually save 

the data in the audit log. If a large amount of data is saved, performance can be impacted. 

When you configure audit data generation for services, you should balance the need for 

audit data against the potential performance impact. 

The following sections describe the options for generating audit data and the potential 

performance impact of each option. 


Enabling Auditing for a Service 


Note: The audit log can be a flat file or a database. If you use a database, the database must 

support JDBC. You can use the Integration Server to view the audit log whether it is a flat 

file or a database. If the audit log is a database, you can also use the webMethods Monitor 

to view audit data and reinvoke the service. Before you configure service auditing, check 

with your Integration Server Administrator to learn what kind of audit log exists. For 

more information about the audit log, see the webMethods Logging Guide. 

When you configure service auditing, you first must decide whether you want to be able 

to audit the service. That is, do you want the service to generate audit data to be captured 

in the audit log? If so, you must decide whether the service will generate audit data every 

time it executes or only when it is invoked directly by a client request (HTTP, FTP, SMTP, 

etc.) or a trigger. 

The following table describes each option for the Enable auditing property in the Properties 

panel. Keep in mind that whenever a service generates audit data, performance can be 

impacted. 

Enable auditing option Description 

Never The service never generates audit data. Select this option 

if you do not want to be able to audit this service. 

When top-level service only The service generates audit data only when it is invoked 

directly by a client request or by a trigger. The service 

does not generate audit data when it is invoked by 

another service (that is, when it is a nested service). 

Always The service generates audit data every time it is invoked. 

Select this option if the service is a critical service that 

you want to be able to audit every time it executes. 

Specifying When Audit Data Is Generated 

When you configure service auditing, you can specify the points when the service 

generates audit data. You might want a service to produce audit data when it starts, when 

it ends successfully, when it fails, or a combination of these. Use the options in the Log on 

property on the Properties panel to specify when a service generates audit data. 



Tip! When a service generates audit data, it also produces an audit event. If you want the 

audit event to cause another action to be performed, such as sending an e-mail 

notification, write an event handler. Then subscribe the event handler to audit events. For 

more information about events and event handlers, see Chapter 14, “Subscribing to 

Events”. 

The following table describes each option in the Log on property. Keep in mind that every 

time the service generates audit data, the Integration Server must capture the data and 

write it to the audit log. This can degrade performance. 

Log on option Description 

Error only The service generates audit data only when the service ends 

because of a failure. If the service executes successfully, it will not 

generate audit data. 

Performance Impact: This option impacts performance only when 

the service fails. When a service executes successfully, this option 

does not impact performance. This option offers the smallest 

performance impact of all the options under Log on. 

Error and success The service generates audit data when the service finishes 

executing, regardless of whether it ends because of success or 

failure. The audit log will contain an entry for every time the 

service finishes processing. 

Error, success, and 

start 

Performance Impact: This option impacts performance every time 

the service executes, whether it ends because of error or success. If 

you are concerned only with services that fail, consider using the 

Error only option instead. 

The service generates audit data when it begins executing and 

when it finishes executing. When the service executes to 

completion, the audit log will contain a start entry and an end or 

error entry. 

Generally, most services execute fairly quickly. By the time an 

administrator views the audit log using webMethods Monitor, the 

audit log would probably contain entries for the start and end of 

service execution. Situations where you might want the service to 

generate audit data at the start and end of service execution 

include: 

� To check for the start of long-running services 

� To detect service hangs. 


Log on option Description 

Including the Pipeline in the Audit Log 


In both situations, if service execution began but did not complete, 

the audit log contains an entry for the start of the service, but no 

entry for the end of the service. 

Performance Impact: Of all the options under Log on, this option 

provides the most verbose and expensive type of audit logging. 

Every time it executes, the service generates audit data at two 

points: the beginning and the end. The Integration Server must 

write the audit data to the audit log twice per service execution. 

This requires significantly more disk utilization than the Error only 

and Error and success options. At most, the Error only and Error and 

success options require the Integration Server to write audit data 

once per service execution. 

Note: The service generates audit data only when it satisfies the selected option under 

Enable auditing and the selected option in the Log on property. For example, if When top-level 

service only is selected and the service is not the root service in the flow service, it will not 

generate audit data. 

When you configure service auditing, you can specify whether the server should include a 

copy of the service’s input pipeline in the audit log. If the audit log contains a copy of the 

input pipeline, you can use the webMethods Monitor to perform more extensive failure 

analysis, examine the service’s input data, or reinvoke the service. Use the options in the 

Include pipeline property on the Properties panel to specify when the Integration Server 

should save a copy of the input pipeline in the audit log. 

The pipeline data saved in the audit log is the state of the pipeline just before the 

invocation of the service. It is not the state of the pipeline at the point the service generates 

audit data. 

When Is a Copy of the Input Pipeline Saved in the Audit Log? 

The Integration Server saves a copy of the input pipeline only if the service generates 

audit data and the service satisfies the option selected in the Include pipeline property. For 

example, ServiceA has the following settings on the Properties panel. 


The audit log will contain 

audit and pipeline data 

for this service only if the 

service is invoked by a 

client or trigger and... 

...the service fails. 

Audit log settings for ServiceA 


The audit log will contain the input pipeline for ServiceA only if it is the top-level service 

(invoked directly by a client or a trigger) and the service ends because of failure. If ServiceA 

is not the top-level service or if ServiceA executes successfully, the audit log will not contain 

a copy of the input pipeline. 

Note: Including the pipeline in the audit log is more beneficial when the audit log is a 

database. The Integration Server can save the pipeline to a flat file audit log; however, you 

will not be able to use the pipeline data to reinvoke the service or perform failure analysis. 

The following table describes the options in the Include pipeline property on the Properties 

panel. Keep in mind that saving the input pipeline to the audit log can impact the 

performance of the Integration Server. 

Include pipeline Description 

Never The Integration Server will never save a copy of the service’s input 

pipeline to the audit log. Select this option if you are using a flat file 

for the audit log or if you do not want to be able to resubmit the 

service to the Integration Server. 

Performance Impact: This option requires minimal network bandwidth 

because the Integration Server needs to send only the audit data 

generated by the service to the audit log. 

On errors only The Integration Server saves a copy of the input pipeline to the audit 

log only when the service generates audit data because of failure. 

Select this option if you want to use the resubmission capabilities of 

the webMethods Monitor to reinvoke a failed service. For more 

information about webMethods Monitor, see the webMethods 

Monitor documentation. 

Performance Impact: For successful service invocations, the On errors 

only option requires minimal network bandwidth. Service 

invocations that end in failure require more network bandwidth 

because the Integration Server must save the audit data and the 

input pipeline. The actual network bandwidth needed depends on 

the size of the initial input pipeline. A large pipeline can degrade 

performance because it may negatively impact the rate at which the 

data is saved to the audit log. 


Include pipeline Description 

Service Auditing Use Cases 


Always The Integration Server saves a copy of the input pipeline to the audit 

log every time the service generates audit data. If the service 

generates data at the start and end of execution (Log on is set to Error, 

success, and start), the input pipeline is saved with the audit log entry 

for the start of service execution. If a service does not generate audit 

data, the Integration Server does not include a copy of the input 

pipeline. 

Before you set properties in the Audit category on the Properties panel, decide what type of 

auditing you want to perform. That is, decide what you want to use the audit log for. The 

following sections describe four types of auditing and identify the Audit properties you 

would select to be able to perform that type of auditing. 

Error Auditing 

Select the Always option if you want to be able to use the 

resubmission capabilities of the webMethods Monitor to reinvoke 

the service, regardless of whether the original service invocation 

succeeded or failed. Including the pipeline can be useful if a resource 

experiences a fatal failure (such as hard disk failure). To restore the 

resource to its pre-failure state, you could resubmit all the service 

invocations that occurred since the last time the resource was backed 

up. This is sometimes called a full audit for recovery. 

Performance Impact: The Always option is the most expensive option 

under Include pipeline. This option places the greatest demand on 

network bandwidth because the Integration Server must write a 

copy of the input pipeline to the audit log every time a service 

executes. The actual network bandwidth needed depends on the size 

of the initial input pipeline. A large input pipeline can negatively 

impact the rate at which the data is saved to the audit log. 

Note: If you want audit events generated by a service to pass a copy of the input pipeline to 

any subscribed event handlers, select On errors only or Always. 

In error auditing, you use the audit log to track and reinvoke failed services. To use the 

audit log for error auditing, services must generate audit data when errors occur, and the 

Integration Server must save a copy of the service’s input pipeline in the audit log. 

With webMethods Monitor, you can only reinvoke top-level services (those services 

invoked directly by a client or by a trigger). Therefore, if your intent with error auditing is 



to reinvoke failed services, the service needs to generate audit data only when it is the toplevel 

service and it fails. 

To make sure the audit log contains the information needed to perform error auditing, 

select the following Audit properties. 

For this property... Select this option... 

Enable auditing When top-level service only 

Include pipeline On errors only 

Log on Error only 

To use the audit log for error auditing, use a database as the audit log. 

Service Auditing 

Note: If you want to be able to audit all failed 

invocations of this service, select Always. 

When you perform service auditing, you use the audit log to track which services execute 

successfully and which services fail. You can perform service auditing to analyze the audit 

log and determine how often a service executes, how many times it succeeds, and how 

many times it fails. To use the audit log for service auditing, services need to generate 

audit data after execution ends. 

To make sure the audit log contains the information needed to perform service auditing, 

select the following Audit properties. 



Include pipeline Never 

Log on Error and success 

Note: Configure a service to save a copy of the input 

pipeline only if you intend to reinvoke the service 

using the resubmission capabilities of the 

webMethods Monitor. 

To use the audit log for service auditing, you can use either a flat file or a database as the 

audit log. 


Auditing for Recovery 


Auditing for recovery involves using the audit log to track executed services and service 

input data so that you can reinvoke the services. You might want to audit for recovery in 

the event that a resource experiences a fatal failure, and you want to restore the resource 

to its pre-failure state by resubmitting service invocations. 

When auditing for recovery, you want to be able to resubmit failed and successful 

services. The audit log needs to contain an entry for each service invoked by a client 

request or a trigger. The audit log also needs to contain a copy of each service’s input 

pipeline. 

To use the audit log to audit for recovery, select the following Audit properties. 



Include pipeline Always 

Log on Error and success 

To use the audit log to audit for recovery, use a database for the audit log. 

Auditing Long-Running Services 

If a service takes a long time to process, you might want to use the audit log to verify that 

service execution started. If the audit log contains a start entry for the service but no end 

or error entry, then you know that service execution began but did not complete. To 

enable auditing of long-running services, select the Error, success, and start option for the 

Log on property. 

Note: Typically, you will audit long-running services in conjunction with error auditing, 

service auditing, or auditing for recovery. 

Setting Auditing Options for a Service 

The following procedure explains how to set auditing options for a service. The options 

you select determine if and when a service generates audit data, and whether the audit log 

includes a copy of the service’s input pipeline. Make sure that you select options that will 

provide the audit log with the audit data you require. 

Important! Before you select options for generating audit data, check with your Integration 

Server Administrator to determine what kind of audit log exists. An audit log can be a flat 

file or a database. 


To set auditing options for a service 


1 Open the service for which you want to configure service auditing. To configure 

service auditing, you must have write access to the service and own the lock on the 

service. 


3 In the Audit category of the Properties panel, select an Enable auditing option to indicate 

when you want the service to generate audit data. 

For more information about the Enable auditing options, see “Enabling Auditing for a 

Service” on page 149. 

4 For Include pipeline, select an option to indicate when the Integration Server should 

include a copy of the input pipeline in the audit log. 

Note: If you want audit events generated by this service to pass a copy of the input 

pipeline to any subscribed event handlers, select On errors only or Always. 

For more information about the Include pipeline options, including information about 

the performance impact, see “Including the Pipeline in the Audit Log” on page 151. 

5 For Log on, select an option to determine when the service generates audit data. 

For more information about the Log on options, including information about the 

performance impact, see “Specifying When Audit Data Is Generated” on page 149. 


Important! The options you select in the Audit category of the Properties panel can be 

overwritten at run time by the value of the watt.server.auditLog server property. 

Audit Level Settings in Earlier Versions of Developer 

In earlier versions of Developer, you could configure audit level settings using the Audit 

level field on the Settings tab. In this field, you could select one of three audit levels for a 

service: off, brief, or verbose. Because the auditing options on the Properties panel offer 

more control over the generation of audit data, the audit level settings are no longer 

available. Each of the earlier Audit level settings corresponds to a combination of options on 

the Properties panel. 

The following table indicates how the Audit level values from webMethods Developer 4.6 

(and earlier) correspond to the properties on the Properties panel. 


Printing a Flow Service 

Input/Output 

parameters 

Body of the flow 

Details of each 

flow step 

Audit Level in 

Developer 4.x Enable auditing Include pipeline Log on 


None Never Never -- 

Brief Always Never Error, success, and start 

Verbose Always Always Error, success, and start 

The following procedure describes how to use the View as HTML command to produce a 

printable version of a flow service. This lets you see all aspects of a flow (its input and 

output parameters, its flow steps, and pipeline behavior) in a single document. 

A flow report lets you view all aspects of the flow service at once 


To print a flow service 

1 In the editor, select the service that you want to print. 

2 From the File menu, click View as HTML. 

3 If you want to print the flow, select your browser’s print command. 


Note: When you print a flow service as HTML, only the flow steps currently visible in the 

editor appear in the resulting HTML page. To fit all of the steps in a flow service into the 

editor (and therefore, into a single HTML page), hide the Navigation, Recent Elements, 

Properties, and Results panels to maximize the editor. 


Chapter 7. Inserting Flow Steps 

� What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 

� Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 

� The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 

� The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 

� The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

� The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 

� The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 

� The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 

� The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 


What Is a Flow Step? 

7. Inserting Flow Steps 

A flow step is the basic unit of work that instructs webMethods Integration Server about 

what to do with data at each stage of a flow service. Flow steps can invoke services and 

direct the course of execution. Using flow steps you can: 

� Invoke a service, such as a flow service, Java service, C service, or Web service 

connector (INVOKE). 

� Conditionally execute one step from a set of specified alternatives (BRANCH). 

� Repeat a set of flow steps up to a specified number of times or until a step in the set 

fails or succeeds as specified (REPEAT). 

� Group a set of flow steps and control the way in which the failure of a member of the 

set is processed (SEQUENCE). 

� Repeat a set of flow steps over the elements of a specified array (LOOP). 

� Exit the entire flow or exit a single flow step (EXIT). 

� Link, add, edit, and delete pipeline variables or invoke several services that operate 

on the same set of pipeline variables (MAP). 

Inserting and Moving Flow Steps 

To insert flow steps in a flow service, you must open the service in the editor. The flow 

steps in the service are listed in the editor. (If you just created the service and it does not 

yet contain any default logic, the editor is empty). 


Flow steps are 

displayed in 

the editor. 

Displaying the steps in a flow service 


Note: You might find it helpful to declare the input and output parameters for a flow 

service before you insert flow steps. By first declaring the parameters, it is clear what data 

the service expects and what variables are available for use in flow steps. 

You insert flow steps into a service using the following toolbar buttons at the top of the 

editor. (You cannot directly type a flow step into the editor. All editing is performed 

through the toolbar). 

To insert a/an... Click this button... For more information, see page... 

INVOKE step 165 

MAP step 192 

BRANCH step 168 

LOOP step 186 



To insert a/an... Click this button... For more information, see page... 

REPEAT step 179 

SEQUENCE step 185 

EXIT step 190 

Note: If you select an existing step in the editor before inserting a new one, Developer 

inserts the new step below the one that is selected. If you do not have a step selected, it 

adds the new step to the end of the flow. You can move a step to a new location using the 

arrow buttons on the toolbar. See the following section, “Changing the Position of a Flow 

Step”. 

Changing the Position of a Flow Step 

Flow steps run in the order in which they appear in the editor. To move a step up or down 

in a flow service, first select that step in the editor and then use the arrow buttons on the 

toolbar to move the step up or down in the list. 

To... Click this button... 

Move the flow step up in the list 

Move the flow step down in the list 

You can also move a flow step by dragging it up or down with your mouse or by using the 

Shift commands on the Compose menu. 

Changing the Level of a Flow Step 

Some flow steps have subordinate steps on which they operate. Subordinate steps are 

referred to as children. For example, when you use the LOOP step, the set of steps that 

make up the loop are referred to as children of that LOOP step. 

Children are specified by indenting them beneath their parent flow step. In the following 

example, the top LOOP step has nine children. Note that one of its children is a BRANCH 

step, which has its own set of children. 


These steps are 

“children” of the 

BRANCH step. 

This step is a “child” 

of the LOOP step. 

Child steps are indented beneath their parent step 


To promote or demote a flow step within a parent/child hierarchy, select the step in the 

editor, and then use one of the following buttons to move it left or right beneath the 

current parent step. 

To... Click this button... 

Demote a flow step in the hierarchy (that is, make the selected step 

a child of the preceding parent step) 

This button will only be available if you select a step that can 

become a child. 

Promote a flow step in the hierarchy (that is, move the step one 

level up in the hierarchy) 

Setting the Properties of a Flow Step 

Every flow step is associated with a unique set of properties. The properties for a flow 

step are displayed in the Properties panel. Values that you specify in the Properties panel 

apply only to the selected step in the editor. 


Use the Properties 

panel to view and set 

the properties of a 

flow step. 

Properties of a flow step 


Although each type of flow step has a set of unique properties, they all have the following 

properties: 

Property Description 

Comments Assigns an optional descriptive comment to the selected flow step. 

Label Assigns a name to the selected flow step. When a label is assigned, that 

label appears next to the step in the editor. The label allows you to 

reference that flow step in other flow steps. In addition, you use the label 

to control the behavior of certain flow steps. For example, the BRANCH 

step uses the Label property to determine which alternative it is 

supposed to execute. 

See “The BRANCH Step” on page 168 and “The EXIT Step” on page 190 

for additional information about this use of the label property. 

For a complete description of the properties associated with each flow step, see 

Appendix A, “webMethods Flow Steps”. 


The INVOKE Step 


You use the INVOKE step to request a service within a flow. You can use the INVOKE step 

to: 

� Invoke any type of service, including other flow services and Web service connectors. 

� Invoke any service for which the caller of the current flow has access rights on the 

local webMethods Integration Server. 

� Invoke built-in services and services on other webMethods Integration Servers. 

� Invoke flow services recursively (that is, a flow service that calls itself). If you use a 

flow service recursively, bear in mind that you must provide a means to end the 

recursion. 

� Invoke any service, validating its input and/or output. For details, see “Performing 

Input/Output Validation” on page 266. 

Flow service containing INVOKE steps 

Specifying the Service Property 

The INVOKE step’s Service property specifies which service will be invoked at run time. 

When you insert an INVOKE step, Developer automatically assigns the name of that 

service to the Service property. 

If you want to change the service assigned to an INVOKE step, you edit the Service 

property. You edit this property in one of two ways: 

� By clicking the Service property’s edit button ( ) and selecting a service from the 

Select dialog box. This is the preferred method. 

� By typing the name of a service in the Service text box. When you specify a service in 

this manner, keep the following points in mind: 



� You must specify the service’s fully qualified name in folderName:serviceName 

format. 

Example purchasing.orders:getOrders 

� You must specify the service’s name exactly as it is defined on the server. Service 

names are case sensitive. 

Invoking a Built-In Service 

There is an extensive set of built-in services that you can invoke from a flow service. The 

webMethods library includes services for doing such things as transforming data values, 

performing simple mathematical operations, extracting information from XML 

documents, and accessing databases. 

Built-in services reside in the WmPublic package. For a complete description of these 

services, see the webMethods Integration Server Built-In Services Reference. 

Note: If you are using any adapters (for example, the webMethods JDBC Adapter), you 

will have additional built-in services, which are provided by the adapters. See the 

documentation provided with those adapters for details. 

Invoking a Service on Another webMethods Integration 

Server 

You can use the built-in service pub.remote:invoke to invoke a service on a remote Integration 

Server and return the results. The remote server is identified by an alias, which is 

configured on the Remote Servers screen in the Integration Server Administrator. The 

pub.remote:invoke service automatically handles opening a session and authentication on the 

remote server. 

The pub.remote:invoke service resides in the WmPublic package and requires the alias of the 

remote server and the fully qualified name of the service that you want to invoke as input. 

For a complete description of this service, see the webMethods Integration Server Built-In 



Building an INVOKE Step 

Use the following procedure to invoke a service within a flow service. 

To build an INVOKE step 


1 Open the flow service in which you want to invoke another service. In the editor, 

select the step immediately above which you want to insert the INVOKE step. 

2 Click on the editor toolbar and then select the service you want to invoke. If the 

service you want to invoke does not appear in the list, click Browse to navigate to and 

select the service. 

Tip! You can also add invoke steps by selecting one or more services in the Navigation 

panel and dragging them to the desired position within the flow in the editor. The 

services must reside on the same server as the flow service. 

3 Complete the following fields on the Properties panel: 

For this property... Specify... 

Service The fully qualified name of the service that will be invoked at 

run time. When you insert a service, Developer automatically 

assigns the name of that service to the Service property. If you 

want to change the service that is invoked, specify the service’s 

fully qualified name in the format folderName:serviceName or 

click and select a service from the list. 

Timeout Optional. Specifies the maximum number of seconds that this 

step should run. If this time elapses before the step completes, 

the server waits for the step to complete and then raises an 

exception. 

If you want to use the value of a pipeline variable for this 

property, type the variable name between % symbols. For 

example, %expiration%. 

If you do not need to specify a time-out period, leave Timeout 

blank. 

Validate input Whether or not you want the server to validate the input to the 

service against the service input signature. Select True to 

validate the input. Select False if you do not want to validate 

the input. 

For information about validating input, see “Performing 



The BRANCH Step 



Validate output Whether or not you want the server to validate the output of 

the service against the service output signature. Select True to 

validate the output. Select False if you do not want to validate 

the output. 

4 If necessary, on the Pipeline tab, link Pipeline In variables to Service In variables. Link 

Service Out variables to Pipeline Out variables. For more information about linking 

variables to a service, see “Linking Variables” on page 201. 

The BRANCH step allows you to conditionally execute a step based on the value of a 

variable at run time. For example, you might use a BRANCH step to process a purchase 

order one way if the PaymentType value is “CREDIT CARD” and another way if it is 

“CORP ACCT”. 

When you build a BRANCH step, you can: 

For information about validating output, see “Performing 


Tip! When you install Developer, the Insert menu displays a list of commonly used 

services. You can use the Tools�Options command to customize this list of services to suit 

your needs. 

� Branch on a switch value. Use a variable to determine which child step executes. At run 

time, the BRANCH step matches the value of the switch variable to the Label property 

of each of its targets. It executes the child step whose label matches the value of the 

switch. 

� Branch on an expression. Use an expression to determine which child step executes. At 

run time, the BRANCH step evaluates the expression in the Label property of each 

child step. It executes the first child step whose expression evaluates to “true.” 

Important! You cannot branch on a switch value and an expression for the same BRANCH 

step. If you want to branch on the value of a single variable and you know the possible 

run-time values of the switch variable exactly, branch on the switch value. If you want to 

branch on the values of more than one variable or on a range of values, branch on 

expressions. 


Each conditional step 

has a label that matches 

the value that causes it 

to execute. 

Branching on a Switch Value 


When you branch on a switch value, you branch on the value of a single variable in the 

pipeline. 

To branch on a switch value 

1 Create a list of the conditional steps (target steps) and make them children of the 

BRANCH step. 

2 In the Properties panel for the BRANCH step, specify in the Switch property the name 

of the pipeline variable whose value will act as the switch. For more information 

about this property, see “Specifying the Switch Variable” on page 170. 

3 In the Label property of each target step, specify the value that will cause that step to 

execute. For more information about this property, see “Specifying the Label Value” 

on page 170. 

Simple BRANCH step that branches on a switch value 

The switch property of 

the BRANCH step 

specifies the name of 

the variable that acts 

as the switch. 


If PaymentType is 

“COD,” execution will 

fall through this 

BRANCH step. 

Specifying the Switch Variable 

The variable you use as the switch variable: 

� Must be a String or constrained Object variable. 


� Must be a variable that can exist in the pipeline when the BRANCH step is executed at 

run time. 

� Must be formatted as document/documentVariable, if you are specifying a field in a 

document as the switch variable (for example, BuyerInfo/AccountNum). 

Specifying the Label Value 

At run time, the BRANCH step compares the value of the switch variable to the Label 

property of each of its targets. It executes the target step whose label matches the value of 

the switch variable. 

You can use a regular expression to specify the matching value for a BRANCH step. To do 

so, use the following syntax to specify the value in Label: 

/RegularExpression/ 

For example, if you want to select a step based on whether a PO number starts with the 

string “REL” you use /^REL/ as the value of Label. For more information about regular 

expressions, see Appendix B, “Regular Expressions”. 

Unlike other flow steps whose children execute in sequence at run time, only one child of a 

BRANCH step is executed: the target whose label matches the value of the switch 

variable. If none of the targets match the switch variable, none of them are performed, and 

execution “falls through” to the next step in the flow service. For example, in the 

following flow service, execution passes directly to the LogTransaction service if the value of 

PaymentType is “COD.” 

An unmatched value will fall though the BRANCH 



Keep the following points in mind when assigning labels to the targets of the BRANCH 

step: 

� You must give each target step a label unless you want to match an empty string. For 

that case, you leave the Label property blank. For more about matching an empty 

string, see “Branching on Null and Empty Values” on page 172. 

� Each Label value must be unique within the BRANCH step. 

� When you specify a literal value as the Label of a child step, the value you specify must 

match the run-time value of the switch variable exactly. The Label property is case 

sensitive. 

� You can use a regular expression as the value of Label instead of a literal value. 

� You can match a null value by using the $null value in the Label property. For more 

information about specifying a null value, see “Branching on Null and Empty Values” 

on page 172. 

� You can designate a default step for all unmatched cases by using the $default value in 

the Label property. For more information about using the $default setting, “Specifying a 

Default Step” on page 174. 

Branching on an Expression 

When you branch on an expression, you assign an expression to each child of a branch 

step. At run time, the BRANCH step evaluates the expressions assigned to the child steps. 

It executes the first child step with an expression that evaluates to true. 

To branch on an expression 

1 Create a list of the conditional steps (target steps) and make them children of the 

BRANCH step. 

2 In the Properties panel for the BRANCH step, set Evaluate labels to True. 

3 In the Label property of each target, specify the expression that, when true, will cause 

the target step to execute. The expressions you create can include multiple variables 

and can specify a range of values for variables. Use the syntax provided by 

webMethods to create the expression. For more information about expression syntax, 

see Appendix D, “Conditional Expressions”. 


Each target step has an 

expression as the label. 

Simple BRANCH step that branches on an expression 

When set to true, the 

Evaluate labels property 

indicates the step 

branches on expressions. 


Keep in mind that only one child of a BRANCH step is executed: the first target step 

whose label contains an expression that evaluates to true. If none of the expressions 

evaluate to true, none of the child steps are invoked, and execution falls through to the 

next step in the flow service. You can use the $default value in the Label property to 

designate a default step for cases where no expressions evaluate to true. For more 

information about using the $default value, see “Specifying a Default Step” on page 174. 

Important! The expressions you create for the children of a BRANCH step need to be 

mutually exclusive (only one condition should evaluate to true at run time). 

Branching on Null and Empty Values 

When you build a BRANCH step, you can include target steps that match null or empty 

switch values. The BRANCH step considers a switch value to be null if the variable does 

not exist in the pipeline or is explicitly set to null. The BRANCH step considers a switch 

value to be an empty string if the variable exists in the pipeline but its value is a zero length 

string. To branch on null or empty values, set the Label property for the target step as 

follows. 


To BRANCH on... Do the following... 


A null value Set the Label property to $null. At run time, the BRANCH step 

executes the target step with the $null label if the switch variable is 

explicitly set to null or does not exist in the pipeline. 

You can use $null with any type of switch variable. 

An empty string Leave the Label property blank (empty). At run time, the BRANCH 

step executes the target step with no label if the switch variable is 

present, but contains no characters. 

You can use an empty value only when the switch variable is of 

type String. 

Important! If you branch on expressions (Evaluate labels is set to True), you cannot branch on 

null or empty values. When executing the BRANCH step and evaluating labels, the server 

ignores target steps with a blank or $null label. 

The following example shows a BRANCH step used to authorize a credit card number 

based on the buyer’s credit card type (CreditCardType). It contains three target steps. The 

first target step handles situations where the value of CreditCardType is null or where 

CreditCardType does not exist in the pipeline. The second target step handles cases where 

the value of CreditCardType is an empty string. (Note that the first two target steps are 

EXIT steps that will return a failure condition when executed.) The third target step has 

the $default label, and will process all specified credit card types. 


This target step executes 

when CreditCardType is 

null or does not exist. 

This target step 

executes when the 

CreditCardType value is 

a zero length string. 

BRANCH that contains target steps to match null values or empty strings 

Specifying a Default Step 


If you want to prevent the service from falling through a BRANCH step when an 

unmatched value occurs at run time, include a default target step to handle unmatched 

cases. To specify the default alternative of a BRANCH step, set the Label property to 

$default. 

The following example shows a BRANCH step that is used to authenticate payment for an 

order based on the type of payment (PaymentType). It contains three target steps. The first 

target step handles orders paid for by Credit Card. The second target step handles orders 

paid for through a Corporate Account. The third target step has the $default label and will 

process all other payment types. 


The first two target steps 

handle credit card and 

corporate account 

payments... 

...and the $default 

target step handles 

the rest. 

The default step is set to $default 

Using SEQUENCE as the Target of a BRANCH 


Important! You can only have one default target step for a BRANCH step. Developer 

always evaluates the default step last. The default step does not need to be the last child of 

the BRANCH step. 

In many cases, you may want a BRANCH step to conditionally execute a series of 

multiple steps rather than just a single step. For these cases, you can use the SEQUENCE 

step as the target step and group a series of flow steps beneath it. 

The following example illustrates a service that accepts a purchase order and processes it 

one of three ways depending on the payment type specified in the PaymentType variable. 

Because a series of steps are needed to process the PO in each case, the targets of the 

BRANCH are defined as SEQUENCE steps, and the appropriate series of steps are 

specified as children beneath each SEQUENCE. 


Create a SEQUENCE 

for each multi-step 

alternative... 

...and then specify the 

appropriate series of 

flow steps as children 

beneath each 

SEQUENCE. 

Use a SEQUENCE step as the target for a multi-step alternative 

Define a multi-step alternative in a SEQUENCE 


The SEQUENCE step that you use as a target for a BRANCH can contain any valid flow 

step, including additional BRANCH steps. For additional information about building a 

SEQUENCE, see “The SEQUENCE Step” on page 185. 


Building a BRANCH Step 

Use the following procedure to build a BRANCH step in a flow service. 

To build a BRANCH step 


1 If you are inserting a BRANCH step into an existing flow service, display that service 

in the editor and highlight the step immediately above where you want the BRANCH 

step inserted. 

2 Click on the editor toolbar. 



Comments An optional descriptive comment for this step. 

Scope The name of a document (IData object) in the pipeline to which 

you want to restrict this step. If you want this step to have 

access to the entire pipeline, leave this property blank. 

Timeout The maximum number of seconds that this step should run. If 

this time elapses before the step completes, the server waits for 

the step to complete and then raises an exception. 


property, type the variable name between % symbols (for 

example, %expiration%). 


blank. 

Label An optional name for this specific step, or a null, unmatched, 

or empty string ($null, $default, blank). For more information 

about branching on null or empty values, see “Branching on 

Null and Empty Values” on page 172. 

Note: If you use this step as a target for another BRANCH or an 

EXIT step, you must specify a value in the Label property. For 

more information about the EXIT step, see “The EXIT Step” on 

page 190. 




Switch The name of the String or constrained Object variable whose 

value will be used to determine which child step to execute at 

run time. Do not specify a switch variable if you set the 

Evaluate labels property to True. 

Evaluate labels Whether or not you want to evaluate labels of child steps as 

conditional expressions. Select True to branch on expressions. 

Select False (the default) if you want to branch on the switch 

value. 

4 Insert the conditional steps that belong to the BRANCH (that is, its children) using the 

following steps: 

a Insert a flow step using the buttons on the editor toolbar. 

b Indent the flow step using on the editor toolbar to make it a child of the 

BRANCH step. 

c In the Label property on the Properties panel, specify the switch value that will 

cause this step to execute at run time. 

To match... Specify... 

That exact string A string 

The String representation of the object’s value 

A constrained 

Example for Boolean object true 

object value 

Example for Integer object 123 

Any string fitting the criteria specified by the regular 

expression 

Example /^REL/ 

d Set other properties as needed. 

A regular 

expression 

An empty string A blank field 

A null value $null 

Any unmatched value (that is, execute the step if the 

value does not match any other label) 

$default 


The REPEAT Step 

This INVOKE step is 

repeated up to 10 times 

if it fails at run time. 


Important! If you are branching on expressions, make sure the expressions you assign to the 

target steps are mutually exclusive. In addition, do not use null or empty values as labels 

when branching on expressions. The BRANCH step ignores target steps with a $null label 

or blank label. 

The REPEAT step allows you to conditionally repeat a sequence of child steps based on 

the success or failure of those steps. You can use REPEAT to: 

� Re-execute (retry) a set of steps if any step within the set fails. This option is useful to 

accommodate transient failures that might occur when accessing an external system 

(for example, databases, ERP systems, Web servers, or Web services) or device. 

� Re-execute a set of steps until one of the steps within the set fails. This option is useful for 

repeating a process as long as a particular set of circumstances exists (for example, 

data items exist in a data set). 

Use REPEAT to re-execute one or more steps 


Specifying the REPEAT Condition 


When you build a REPEAT step, you set the Repeat on property to specify the condition 

(success or failure) that will cause its children to re-execute at run time. 

If you set “Repeat on” to… The REPEAT step… 

FAILURE Re-executes the set of child steps if any step in the set fails. 

SUCCESS Re-executes the set of child steps if all steps in the set 

complete successfully. 

Setting the REPEAT Counter 

The REPEAT step’s Count property specifies the maximum number of times the server reexecutes 

the child steps in the REPEAT step. 

If you set “Count” to… The REPEAT step… 

0 Does not re-execute children. 

Any value > 0 Re-executes children up to this number of times. 

-1 or blank Re-executes children as long as the specified Repeat on 

condition is true. 

Important! Note that children of a REPEAT always execute at least once. The Count property 

specifies the maximum number of times the children can be re-executed. At the end of an 

iteration, the server checks to see whether the condition (that is, failure or success) for 

repeating is satisfied. If the condition is true and the Count is not met, the children are 

executed again. This process continues until the repeat condition is false or Count is met, 

whichever occurs first. (In other words, the maximum number of times that children of a 

REPEAT will execute when Count is > -1, is Count+1.) 

When Does REPEAT Fail? 

The following conditions cause the REPEAT step to fail: 

If “Repeat on” is set to… The REPEAT step fails if… 

SUCCESS A child within the REPEAT block fails. 

FAILURE The Count limit is reached before its children execute 

successfully. 

If the REPEAT step is a child of another flow step, the failure is propagated to its parent. 


Using REPEAT to Retry a Failed Step 


If your flow invokes services that access external systems, you can use the REPEAT step to 

accommodate network errors, such as busy servers or connection errors, at run time. If 

you use the REPEAT step for this purpose, keep the following points in mind: 

� The following types of failures satisfy the FAILURE condition: 

� Expiration of a child step’s Timeout limit 

� An exception thrown by a Java service 

� A document query that returns an unpermitted null value 

� If you specify multiple children under a REPEAT step, the failure of any one of the 

children will cause the entire set of children to be re-executed. 

� The REPEAT step immediately exits a set of children at the point of failure (that is, if 

the second child in a set of three fails, the third child is not executed). 

� When Repeat on is set to FAILURE, the failure of a child within a REPEAT step does 

not cause the REPEAT step itself to fail unless the Count limit is also reached. 

� The Timeout property for the REPEAT step specifies the amount of time in which the 

entire REPEAT step, including all of its possible iterations, must complete. When you 

use REPEAT to retry on failure, you may want to leave the Timeout value at 0 (no limit) 

or set it to a very high value. You can also set the property to the value of a pipeline 

variable by typing the name of the variable between % symbols. 

� As a developer, you must be thoroughly familiar with the processes you include 

within a REPEAT step. Make certain that the child steps you specify can safely be 

repeated in the event that a failure occurs. You don’t want to use REPEAT if there is 

the possibility that a single action, such as accepting an order or crediting an account 

balance, could be applied twice. 

To build a REPEAT step that re-executes failed steps 

1 If you are inserting a REPEAT step into an existing flow service, display that service in 

the editor and highlight the step immediately above where you want the REPEAT 











Timeout The maximum number of seconds that this step should run. If 







blank. 

Label An optional name for this specific REPEAT step, or a null, 

unmatched, or empty string ($null, $default, blank). 

Important! If you use this step as a target for a BRANCH or 

EXIT step, you must specify a value in the Label property. For 

more information about the BRANCH and EXIT steps, see 

“The BRANCH Step” on page 168 or “The EXIT Step” on 

page 190. 

Count The maximum number of times you want the children to be 

re-executed. If you want to use the value of a pipeline variable 

for this property, type the variable name between % symbols 

(for example, %servicecount%). 

If you want the children re-executed until they are all 

successful (that is, no maximum limit), set this value to –1. 

Repeat interval The length of time (in seconds) that you want the server to 

wait between iterations of the children. 



example, %waittime%). 

Repeat on FAILURE 



4 Beneath the REPEAT step, use the following steps to insert each step that you want to 

repeat: 


b Indent that flow step using on the editor toolbar. (Make it a child of the 

REPEAT step.) 

c Set the properties for the child step as needed. 

Using REPEAT to Retry a Successful Step 

Apart from using REPEAT to retry a failed step, you can also use it as a looping device to 

repeat a series of steps until a failure occurs. 

If you use the REPEAT step to re-execute successful child steps, keep the following points 

in mind: 

� The success condition is met if all children of the REPEAT step execute without 

returning a single exception. 

� If one child in the set fails, the REPEAT step exits at the point of failure, leaving the 

remaining children unexecuted. 

� The failure of a child does not cause the REPEAT step to fail; it merely ends the loop. 

(In this case, the REPEAT step itself succeeds and execution of the flow proceeds 

normally). 

To build a REPEAT step that repeats a set of successful steps 

1 If you are inserting a REPEAT step into an existing flow service, display that service in 

the editor and highlight the step immediately above where you want the REPEAT 












Timeout The maximum number of seconds that this step should run.If 







blank. 


or empty string ($null, $default, blank). 

Important! If you use this step as a target for a BRANCH or 

EXIT step, you must specify a value in the label property. For 

more information about the BRANCH and EXIT steps, see 

“The BRANCH Step” on page 168 or “The EXIT Step” on 

page 190. 

Count The maximum number of times you want the children to be 

re-executed. If you want to use the value of a pipeline variable 

for this property, type the variable name between % symbols 

(for example, %servicecount%). 

If you want the children re-executed until any one of them fails 

(that is, no maximum limit), set this value to –1. 

Repeat interval The length of time (in seconds) that you want the server to 

wait between iterations of the children. 



example, %waittime%). 

Repeat on SUCCESS 

4 Beneath the REPEAT step, use the following steps to insert each step that you want 

repeat: 


b Indent that flow step using on the editor toolbar to make it a child of the 

REPEAT step. 



The SEQUENCE Step 


You use the SEQUENCE step to build a set of steps that you want to treat as a group. Steps 

in a group are executed in order, one after another. By default, all steps in a flow service, 

except for children of a BRANCH step, are executed as though they were members of an 

implicit SEQUENCE step (that is, they execute in order, one after another). However, 

there are times when it is useful to explicitly group a set of steps. The most common 

reasons to do this are: 

� To group a set of steps as a single alternative beneath a BRANCH step. For details 

about this use of the SEQUENCE step, see “Using SEQUENCE as the Target of a 

BRANCH” on page 175. 

� To specify the conditions under which the server will exit a sequence of steps without 

executing the entire set. 

Using SEQUENCE to Specify an Exit Condition 

In an implicit sequence, when a step fails, the server automatically exits the sequence (that 

is, the Exit on property is set to FAILURE). By grouping steps into an explicit sequence, you 

can override this default behavior and specify the condition on which the sequence exits. 

To do this, you set the Exit on parameter as follows: 

If you want the server to… Set “Exit on” to… 

Exit the sequence when a step in the sequence fails. (Execution 

continues with the next flow step in the flow service.) This is the 

default behavior of a sequence of steps. 

This setting is useful if you have a series of steps that build upon 

one another. For example, if you have a set of steps that gets an 

authorization code and then submits a PO, you will want to skip the 

PO submission if the authorization step fails. 

When a SEQUENCE exits under this condition, the SEQUENCE 

step fails. 

Note: When a SEQUENCE step exits on failure, the Integration 

Server rolls back the pipeline contents. That is, the Integration 

Server returns the pipeline to the state it was in before the 

SEQUENCE step executed. 

FAILURE 


The LOOP Step 


If you want the server to… Set “Exit on” to… 

Exit the sequence when any step in the sequence succeeds. 

(Execution continues with the next step in the flow service.) 

This setting is useful for building a set of alternative steps that are 

each attempted at run time. Once one of the members of the set runs 

successfully, the remaining steps in the sequence are skipped. 

When a SEQUENCE exits under this condition, the server considers 

the SEQUENCE step successful, even if all its children fail. If a child 

fails under this condition, any changes that it made to the pipeline 

are rolled back (undone), and processing continues with the next 

child step in the SEQUENCE. 

Execute every step in the sequence even if one of the steps in the 

sequence fails. 

The server considers a SEQUENCE step successful as long as it 

executes all of its children within the specified time-out limit. The 

success or failure of a child within the sequence is not taken into 

consideration. If a child fails under this condition, any changes that 

it made to the pipeline are rolled back (undone), and processing 

continues with the next child step in the SEQUENCE. 

SUCCESS 

The LOOP step repeats a sequence of child steps once for each element in an array that 

you specify. For example, if your pipeline contains an array of purchase-order line items, 

you could use a LOOP step to process each line item in the array. 

To specify the sequence of steps that make up the body of the loop (that is, the set of steps 

you want the LOOP to repeat), you indent those steps beneath the LOOP as shown in the 

following example. 


DONE 

Note: Rollback operations are performed on the first level of the pipeline only. That is, firstlevel 

variables are restored to their original values before the step failed, but the server 

does not roll back changes to any documents to which the first-level variables refer. 

Note: A failure in a MAP step (that is, a failure in one of the transformers) will cause the 

containing SEQUENCE to exit when you set Exit on to FAILURE. However, a MAP step that 

does not fail will not cause the containing SEQUENCE to exit when you set Exit on to 

SUCCESS. That is, a MAP can fail but it does not “succeed.”

The body of the loop 

must be indented 

beneath the LOOP 

step. 

The entire LOOP step 

is a child of the 

outer LOOP. 

Simple LOOP step 


You may include any valid flow step within the body of a LOOP, including additional 

LOOP steps. The following example shows a pair of nested LOOPs. Note how the 

indentation of the steps determines the LOOP to which they belong. 

Nested LOOP steps 

Specifying the Input Array 

The LOOP step requires you to specify an input array that contains the individual 

elements that will be used as input to one or more steps in the LOOP. At run time, the 

LOOP step executes one pass of the loop for each member in the specified array. For 

example, if you want to execute a LOOP for each line item stored in a purchase order, you 

would use the document list in which the order’s line items are stored as the LOOP’s input 

array. 


The LOOP step 

executes once for each 

member of the array 

specified in Input array. 


You specify the name of the input array on the LOOP step’s Properties panel. The array 

you specify can be any of the following data types: 

� String list 

� String table 

� Document list 

� Object list 

LOOP properties 

When you design your flow, remember that because the services within the loop operate 

against individual elements in the specified input array, they must be designed to take 

elements of the array as input, not the entire array. 

For example, if your LOOP executes against a document list called LineItems that contains 

children called Item, Qty, and UnitPrice, you would specify LineItems as the Input array for 

the LOOP step, but services within the loop would take the individual elements of 

LineItems (for example, Item, Qty, UnitPrice, and so forth) as input. 

Collecting Output from a LOOP Step 

If your LOOP step produces an output variable, the server can collect that output into an 

array in the pipeline. 

To do this, you use the Output array parameter to specify the name of the array variable into 

which you want the server to collect output for each iteration of the loop. For example, if 

your loop checks inventory status of each line item in a purchase order and produces a 

String called InventoryStatus each time it executes, you would specify InventoryStatus as 

the value of Output array. At run time, the server will automatically transform 

InventoryStatus to an array variable that contains the output from each iteration of the 

loop. 

To collect output from each pass of the loop, specify the name of the output variable that 

you want the server to collect for each iteration. 


Building a LOOP Step 

Use the following procedure to build a LOOP step in a flow service. 

To build a LOOP step 


1 If you are inserting a LOOP step into an existing flow service, display that service in 

the editor and select the step immediately above where you want the LOOP step 

inserted. 



For this property… Specify… 





Timeout The maximum number of seconds that this step should run.If 







blank. 

Label An optional name for this specific LOOP step, or a null, 


Important! If you use this step as a target for a BRANCH or EXIT 

step, you must specify a value in the Label property. For more 

information about the BRANCH and EXIT steps, see “The 

BRANCH Step” on page 168 or “The EXIT Step” on page 190. 

Input array The name of the array variable on which the LOOP will 

operate. This variable must be one of the following types: 

String list, String table, Document list, Object list. 

Output array The name of the element that you want the server to collect 

each time the LOOP executes. You do not need to specify this 

property if the loop does not produce output values or if you 

are collecting the elements of Input array. 


The EXIT Step 

4 Build the body of the loop using the following steps: 



b Indent the flow step using on the editor toolbar to make it a child of the LOOP 

step. 


5 Use the Pipeline tab to link the elements of the input array to the input variables 

required by each child of the LOOP step. For more information about using the 

Pipeline tab, see Chapter 8, “Mapping Data in a Flow Service”. 

Important! When you build a LOOP step, make sure that you specify the output array 

variable in the LOOP Output array property before creating a link to the output array 

variable within a MAP or INVOKE step in the body of the LOOP. If you specify the output 

array variable after creating a link to it, the link will fail at run time. You can test the step in 

Developer to see if the link succeeds. If the link fails, delete the link to the output array 

variable and then recreate it. 

The EXIT flow step allows you to exit the entire flow service or a single flow step. You 

specify whether you want to exit from: 

� The nearest ancestor (parent) LOOP or REPEAT flow step to the EXIT flow step. 

� The parent flow step of the EXIT flow step. 

� A specified ancestor flow step to the EXIT flow step. 

� The entire flow service. 

When you use the EXIT step, you indicate whether exiting should return a successful 

condition or a failure condition. If the exit is considered a failure, an exception is thrown. 

You can specify the text of the error message that is displayed by typing it directly or by 

assigning it to a variable in the pipeline. 

Examples of when to use the EXIT step include to: 

� Exit an entire flow service from within a series of deeply nested steps. 

� Throw an exception when you exit a flow or a flow step without having to write a 

Java service to call Service.throwError( ). 

� Exit a LOOP or REPEAT flow step without throwing an exception. 

The following flow service contains two EXIT steps that, if executed, will exit the nearest 

ancestor LOOP step. If the value of CreditCardType is null or an empty string, the matching 

EXIT step executes and exits the LOOP over the '/PurchaseOrdersList' step. 


This LOOP exits 

when.... 

...CreditCardType is 

null... 

...or empty. 

Use the EXIT step to exit the nearest ancestor LOOP step 

To build an EXIT step 


1 If you are inserting an EXIT step into an existing flow service, display that service in 

the editor and select the step immediately above where you want the EXIT step 

inserted. 






or empty string ($null, $default, blank). 

Important! If you use this step as a target for a BRANCH step, 

you must specify a value in the Label property. For more 

information about the BRANCH step, see “The BRANCH 

Step” on page 168. 

Exit from The flow step from which you want to exit. Specify one of the 

following: 

Specify To exit from the... 

$loop Nearest ancestor LOOP or REPEAT flow step. 


The MAP Step 



The MAP step lets you adjust the contents of the pipeline at any point in a flow service. 

When you build a MAP step, you can: 

� Prepare the pipeline for use by a subsequent step in the flow service by linking, 

adding, and dropping variables in the pipeline. 

� Clean up the pipeline after a preceding step by removing fields that the step added 

but are not needed by subsequent steps. 

� Move variables or assign values to variables in the pipeline. 

� Initialize the input values for a flow service. 

$parent Parent flow step, regardless of the type of step. 

$flow Entire flow. 

Label Nearest ancestor flow step that has a label that 

matches this value. 

Note: If the label you specify does not match the 

label of an ancestor flow step, the flow will exit 

with an exception. 

Signal Whether the exit is to be considered a success or a failure. 

Specify one of the following: 

Specify… To… 

SUCCESS Exit the flow service or flow step with a success 

condition. 

FAILURE Exit the flow service or flow step with a failure 

condition. An exception is thrown after the exit. 

You specify the error message with the Failure 

message property. 

Failure message The text of the exception message you want to display. If you 

want to use the value of a pipeline variable for this property, 

type the variable name between % symbols (for example, 

%mymessage%). 

This property is not used when Signal is set to SUCCESS. 


� Invoke several services (transformers) in a single step. 


� Map documents form one format to another. For example, you can map a document 

in an XML format to an ebXML format or a proprietary format. 

Tip! The MAP step is especially useful for hard coding an initial set of input values in a 

flow service. To use it in this way, insert the MAP step at the beginning of your flow, and 

then use the Set Value modifier to assign values to the appropriate variables in Pipeline Out. 

For more information about the MAP step, see Chapter 8, “Mapping Data in a Flow 

Service”. 




Chapter 8. Mapping Data in a Flow Service 

� What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 

� What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 

� Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 

� Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 


What Is Data Mapping? 

8. Mapping Data in a Flow Service 

Data mapping is the process of performing transformations to resolve data representation 

differences between services or document formats. By mapping, you can accomplish the 

following types of data transformations: 

� Name transformations where different variable names represent the same data item. For 

example, one service or document format might use Telephone as the name of the 

variable for telephone number information and another might use PhoneNumber. 

When you perform name transformations, the value and position of a variable in the 

document (IData object) structure remain the same, but the name of the variable 

changes. 

� Structural transformations where different data structures represent a data item. For 

example, one service or document format might put the telephone number in a string 

called Telephone, and the next may expect to find it in an element of a document (IData 

object) array called CustInfo. When you perform structural transformations, the value 

of the variable remains the same, but the data type or position of the variable in the 

document (IData object) structure changes. 

� Value transformations where different formats represent the same value. This occurs 

commonly with date and time variables, where, for instance, one variable might use 

“01/01/99” and another “January 1, 1999.” In other cases, your services or document 

formats might use different notations for standard codes or values, different currency 

units, or a different system of weights and measures (metric instead of the U.S. 

Customary or British Imperial systems). When you perform value transformations, 

the name and position of the variable remain the same, but the data contained in the 

variable changes. (For example, you can change the format of a date, concatenate two 

strings, or add the values of two variables together.) 

When you build flow services or convert between document formats, you may need to 

perform one, two, or all of the above types of data transformation. The webMethods flow 

language provides two ways for you to accomplish data transformations between services 

and document formats: you can map variables to each other (create links) or you can 

insert transformers. 

webMethods Developer provides a graphical environment in which you can perform data 

mapping between variables and formats, which is the Pipeline tab. 

What Does the Pipeline Tab Contain? 

The Pipeline tab offers a graphical representation of all of your data through which you can 

map data and inspect the contents of the pipeline. You use the tools on this tab to route 

variables (data) between services or between document formats. 

The Pipeline tab displays in the editor for invoked services (INVOKE steps) or MAP steps 

in a flow service. The contents of this tab for INVOKE steps are slightly different than for 

MAP steps. 


Pipeline Tab for an INVOKE Step 


For an INVOKE step, the Pipeline tab depicts two stages of the pipeline with respect to the 

selected service in the editor. 

Pipeline tab for an INVOKE step (service) 

The Pipeline tab 

depicts the service’s 

input and output with 

respect to the 

expected pipeline. 1 2 

This stage... Represents... 

1 

The expected state of the pipeline just before the selected service 

executes. 

Pipeline In depicts the set of variables that are expected to be in the 

pipeline before the service executes (based on the declared input 

and output parameters of the preceding services). 

Service In depicts the set of variables the selected service expects as 

input (as defined by its input parameters). 

On the Pipeline tab, you can insert “pipeline modifiers” at this stage 

to adjust the contents of the pipeline to suit the requirements of the 

service. For example, you can link variables, assign values to 

variables, drop variables from the pipeline, or add variables to the 

pipeline. Modifications that you specify during this stage are 

performed immediately before the service executes at run time. 


This stage... Represents... 

2 


The expected state of the pipeline just after the service executes. 

Service Out depicts the set of variables that the selected service 

produces as output (as defined by its output parameters). 

Pipeline Out depicts the set of variables that are expected to be in the 

pipeline after the service executes. It represents the set of variables 

that will be available to the next service in the flow. If the selected 

service (INVOKE step) is the last step in the flow service, Pipeline 

Out displays the output variables for the flow service (as declared 

on the Input/Output tab). 

On the Pipeline tab, you can insert “pipeline modifiers” at this stage 

to adjust the contents of the pipeline. For example, you can link 

variables, assign values to variables, drop variables from the 

pipeline, or add variables to the pipeline. Modifications that you 

specify during this stage are performed immediately after the 

service executes at run time. 

Note: Developer displays small symbols next to a variable icon to indicate validation 

constraints. Developer uses to indicate an optional variable. Developer uses the ‡ 

symbol to denote a variable with a content constraint. For information about applying 

constraints to variables, see “Applying Constraints to Variables” on page 261. 


Pipeline Tab for a MAP Step 


For a MAP step, the Pipeline tab displays a single stage of the pipeline. The Pipeline tab 

contains two sets of variables: Pipeline In and Pipeline Out. Between these sets of variables, 

the Pipeline tab contains a column named Transformers. 

Pipeline tab for a MAP step 

� The Pipeline In column represents input to the MAP step. It contains the names of all of 

the variables in the pipeline at this point in the flow. 

� The Transformers column displays any services inserted in the MAP step to complete 

value transformations. For more information about invoking services in a MAP step, 

see “Inserting a Transformer into a MAP Step” on page 224. 

� The Pipeline Out column represents the output of the MAP step. It contains the names 

of variables that will be available in the pipeline when the MAP step completes. 

When you first insert a MAP step into your flow, Pipeline In and Pipeline Out are identical. 

However, if the MAP step is the only step in the flow service or is the last step in the flow 

service, Pipeline Out also displays the variables declared as output in the flow service. 

On the Pipeline tab, you can insert “pipeline modifiers” to adjust the contents of the 

pipeline. For example, you can link variables from Pipeline In to services in Transformers. 

You can also use pipeline modifiers to assign values to pipeline variables, drop variables 

from the pipeline, or add variables to the pipeline. 


Pipeline Modifiers 


Pipeline modifiers are special commands that you apply to adjust the pipeline at run time. 

They execute immediately before or after the selected service or transformer, depending 

on where you add them on the Pipeline tab. Use the following buttons to add pipeline 

modifiers to the pipeline: 

Use this modifier... To... 

Link 

Drop 

Set Value 

Printing the Pipeline Tab 

The following procedure describes how to use the View as HTML command to produce a 

printable version of the Pipeline tab. 

1 Open the flow service for which you want to print the Pipeline tab. 

2 In the editor, select the INVOKE or MAP step for which you want to print the Pipeline 

tab. 

3 Click anywhere on the Pipeline tab. 

Link a pipeline variable to a service variable. The Link modifier lets you 

resolve variable-name and data-structure differences by “linking” 

(copying) the value of one variable to another at run time. For 

information about using this pipeline modifier, see “Linking 

Variables” on page 201. 

Drop a variable from the pipeline. The Drop modifier removes 

extraneous variables from the pipeline. For information about 

using this pipeline modifier, see “Dropping Variables from the 

Pipeline” on page 220. 

Assign a value to a variable. The Set Value modifier “hard codes” a 

value for a variable. For information about this pipeline modifier, 

see “Assigning Values to Pipeline Variables” on page 216. 

Note: When you view the Pipeline tab as HTML, the resulting HTML page displays only the 

portion of the pipeline that is visible within the tab. Before you select the View as HTML 

command, make sure the Pipeline tab displays the part of the pipeline that you want to 

view as HTML. 

To print the Pipeline tab 

4 Scroll or resize the Pipeline tab to display the portion of the pipeline you want to view 

as HTML. 


Basic Mapping Tasks 

5 On the File menu, click View as HTML. 


Developer creates an HTML page and displays it in your default browser. 

6 If you want to print the pipeline, use your browser's print command. 

Basic mapping tasks are the tasks you perform to manage the pipeline contents and the 

values of variables in the pipeline. On the Pipeline tab, you can perform the following basic 

mapping tasks: 

� Link variables to each other. You can copy the value of a variable in one service or 

document format to a variable in another service or document format. 

� Assign values to variables. You can hard code variable values or assign a default value to 

variables. 

� Drop variables from the pipeline. You can remove pipeline variables that are not used by 

subsequent services in a flow. 

� Add variables to the pipeline. You can add variables that were not declared as input or 

output parameters of the flow service. You can also add input and output variables 

for services that the flow service invokes (internally invoked services). 

The following table identifies the sections that describe the basic mapping tasks. 

For more information about... See page... 

Linking variables 201 

Linking variables of different data types 209 

Linking to and from array variables 211 

Deleting links between variables 214 

Applying conditions to links between variables 214 

Assigning values to pipeline variables 216 

Dropping variables from the pipeline 220 

Adding variables to the pipeline 221 

Searching for variables in an editor tree 61 

Linking Variables 

When you want to copy the value of a variable in a service or document format to another 

variable, you link the variables. Developer connects service and pipeline variables on the 

Pipeline tab with a line called a link. Creating a link between variables copies the value 

from one variable to another at run time. 


Pipeline variables are 

automatically linked to 

service variables of the 

same name. 


Within a flow, Developer implicitly links variables whose names are the same and whose 

data types are compatible. For example, the service in the following flow takes a variable 

called AcctNumber. Because a variable by this name already exists in Pipeline In, it is 

automatically linked to the AcctNumber variable in Service In. Developer connects 

implicitly linked variables with a gray link. 

Implicit links between pipeline and service variables 

Important! The Pipeline tab does not display implicit links for a MAP step. 

In cases where the services in a flow do not use the same names for a piece of information, 

use the Pipeline tab to explicitly link the variables to each other. Explicit linking is how you 

accomplish name and structure transformations required in a flow. Developer connects 

explicitly linked variables with a solid black line. 

On the input side of the Pipeline tab, use the Link modifier to link a variable from the 

pipeline to the service. In the following example, the service expects a value called 

OrderTotal, which is equivalent to the pipeline variable BuyersTotal (that is, they are simply 

different names for the same data). To use the value of BuyersTotal as the value for 

OrderTotal, you “link” the pipeline variable to the service using the Link modifier. 

At run time, the server will copy the value from the source variable (BuyersTotal) to the 

target variable (OrderTotal) before executing the service. 


When a pipeline variable 

name is different from the 

one used by the service, 

use the Link modifier to 

connect them. 

Linking the pipeline to service input 


Important! Do not link variables with different Object constraints. If you link variables with 

different object constraints and input/output validation is selected, the run-time result is 

undefined. 

All the output variables that a service produces are automatically placed in the pipeline. 

Just as you can link variables from the Pipeline In stage to a service’s input variables, you 

can link the output from a service to a different variable in Pipeline Out. 

In the following example, a variable called TransNumber is linked to the field Num in a 

document called TransactionRecord. At run time, the server will copy the value of 

TransNumber to Num, and both TransNumber and Num will be available to subsequent 

services in the flow. 


Linking service output to the pipeline 


When an output variable 

name is different from the 

name in the pipeline, use 

the Link modifier to 

connect them. 

When you link variables in the pipeline, keep the following points in mind: 

Developer automatically adds a 

service’s output variables to the 

pipeline and implicitly links them. 

� The variable that you are linking from is the source. For example, when you link a 

variable in Pipeline In to one in Service In, the Pipeline In variable is the source. When you 

link a variable in Service Out to one in Pipeline Out, the Service Out variable is the source. 

� The variable you are linking to is the target. For example, when you link a variable in 

Pipeline In to one in Service In, the Service In variable is the target. When you link a 

variable in Service Out to one in Pipeline Out, the Pipeline Out variable is the target. 

� A Service In variable can be the target of more than one Link modifier only if you use 

array indexing or if you place conditions on the links to the variable. 

� By linking variables to each other, you are copying data from the source variable to the 

target variable. (Documents, however, are copied by reference. For more information, 

see “What Happens When Integration Server Executes a Link Between Variables?” on 

page 206.) 

� Target variables can be connected to only one source variable. After you draw a link to 

a target variable, you cannot draw another link to the target variable. (Two exceptions 

to this rule involve array variables and conditional links. For more information about 

linking array variables, see “Linking to and from Array Variables” on page 211. For 

more information about placing conditions on links between variables, see “Applying 

Conditions to Links Between Variables” on page 214. 



� You cannot create a link to a variable if you already used the Set Value modifier to 

assign a value to a variable. 

� After a Link modifier is executed, both the source and target variables exist in the 

pipeline. The target variable does not replace the source variable. 

To create a link between variables 

1 In the editor, select the INVOKE or MAP step containing the variables you want to 

link. 

2 Click the Pipeline tab. 

3 If you want to create a link between a variable in Pipeline In and one in Service In, do the 

following: 

a In Pipeline In, click the pipeline variable you want to use as the source variable. 

b In Service In, click the input variable you want to use as the target variable. 

c Click on the toolbar. 

4 If you want to create a link between a variable in Service Out and one in Pipeline Out, do 

the following: 

a In Service Out, click the output variable you want to use as the source variable. 

b In Pipeline Out, click the pipeline variable you want to use as the target variable. 

c Click on the toolbar. 

Notes: 

� If the variable types are incompatible and cannot be linked to one another, 

Developer displays a message stating that the operation is not allowed. 

� If you created a link to or from an array variable, you must specify which element 

in the array you are linking to or from. For more information about array linking, 

see “Linking to and from Array Variables” on page 211. 

� If you want to place a condition on the execution of the link, see “Applying 

Conditions to Links Between Variables” on page 214. 

� Do not link variables with different Object constraints. If you link variables with 

different object constraints and input/output validation is selected, the run-time 

result is undefined. 

Tip! You can also use your mouse to link variables to one another. To do this, select the 

source variable and drag your mouse to the appropriate target variable. 



Tip! To scroll through the Pipeline In and Pipeline Out trees independently, display the 

left-hand scroll bar. Click to display the left-hand scroll bar. Click to hide the 

left-hand scroll bar. The left-hand scroll bar is only available on the Pipeline tab for a MAP 

step. When you expand a transformer, Developer hides the left-hand scroll bar 

automatically. 

What Happens When Integration Server Executes a Link Between Variables? 

When executing a link between variables at run time, Integration Server does one of the 

following: 

� Copies the value from the source variable to the target variable. For example, when 

you link a source String variable to a target String variable, Integration Server copies 

the value of the source String to the target String. This is called “copying by value.” 

� Creates a reference to the source variable and uses the reference as the value of the 

target variable. For example, when executing a link between a source document and a 

target document, Integration Server creates a reference to the source document value 

and uses the reference as the value of the target document. This is called “copying by 

reference.” 

Integration Server copies by value when the source or target variable is a String. (An 

exception to this behavior is that when executing a link from a String to an Object, the 

Integration Server copies by reference.) 

When executing links between all other types of variables, the Integration Server copies by 

reference. Copying by reference significantly reduces the memory and time required for 

executing a link at run time. 

When a value is copied by reference, any changes you make to the value of the source 

variable in subsequent flow steps affect the target variable. This is because the value of the 

source variable is the value of the target variable. The target variable does not contain a 

copy of the source variable value. If, in a later flow step, you used the Set Value modifier to 

assign a value to the source variable, you would be changing the value of the target 

variable as well. (The target variable references the value of the source variable.) 

The following images show a series of MAP steps in a flow service. In this example, the 

value of the source variable is changed after the link to the target variable executes. This 

action changes the value of the target variable as well. 


The value of String1 is set 

to “original value”. 

Document1 is linked to 

Document2. After the link 

executes, the value of 

Document2 is a reference 

to the contents of 

Document1. 

The value of String1 is 

changed to “modified”. 

This action changes the 

value of the string in 

Document2 as well. 

Step 1: The value of String1 is set to “original value” 

Step 2: Document1 is linked to Document2 

Step 3: The value of String1 is changed to “modified” after the link executes 



The String1 in 

Document1 and the 

String1 in Document2 

have the same value 

because Document1 

was copied to 

Document2 by 

reference. 

When this flow service executes, it returns the following results. 

Results of flow service 


In Step 3, the value of the String1 in Document1 was set to “modified.” However, the 

value of String1 in Document2 changed also. This is because in Step 2 of the flow service, 

the value of Document1 was copied to Document2 by reference. Changes to the value of 

Document1 in later flow steps also change the value of Document2. 

To prevent the value of the target variable from being overwritten by changes to the value 

of the source value in subsequent steps in the flow service, you can do one of the 

following: 

� When working with document variables, link each child of the document variable 

individually. This method can be time consuming and might significantly increase the 

memory and time required to run the service. However, this might be the best 

approach if the target document variable needs only a few values from the source 

document variable. 

� After you link the source variable to a target variable, use the Drop modifier to drop 

the source variable. Only the target variable will have the reference to the data. This 

method ensures that the value of the target variable will not be overwritten in a 

subsequent step, but does not increase the memory and time required to execute the 

service. 

� Create a service that performs a copy by value. Insert this service (as an INVOKE step 

or as a transformer) and link the variables to the service instead of linking them to 

each other. (In the case of document variables, you could create a Java service that 

clones the IData object underlying the document.) In situations where you link one 

document variable to another, using a “cloning” service would require less time than 

linking the contents of a document variable field by field. 

Linking to Document and Document List Variables 

When working with document variables in the pipeline, you can link a source variable to 

the document variable or to the children of the document variable. Keep the following 

points in mind when linking to document or document list variables: 

� A document (or a document list) and its children cannot both be targets. After a 

document or document list is the target of a Link modifier, its children cannot be the 

targets of Link modifiers. 



� After the child variable of a document or document list is the target of a Link modifier, 

the parent document or document list cannot be a target of a Link modifier. 

� If you link from a document variable to another document variable, the structure of 

the source document variable overwrites the structure of the target document 

variable. 

Linking Variables of Different Data Types 

On the Pipeline tab, you can link different, but compatible, data types to one another. For 

example, you could link a String value called AccountNumber to a String list called 

Accounts. At run time, the server automatically performs the structural transformation 

necessary to link the data in AccountNumber to Accounts. (In this case, the transformation 

will result in a single-element String list.) By linking different data types to one another, 

you can perform structural transformations. 

If you link variables of different data types, keep the following points in mind: 

� Not all data types can be linked to one another. You cannot link a document (IData 

object) to a String, for instance. If two data types are incompatible, Developer will not 

allow you to connect them with the Link modifier. 

� You can only link a variable to another variable of the same primitive type. The 

primitive type refers to the data type of the variable when all dimensionality is 

removed. For example, the primitive type for a String list or a String table would be 

String. Two exceptions to this rule are: any variable can be linked to an Object or an 

Object list variable, and an Object can be linked to any data type. (If there is a type 

mismatch between the Object or Object list and the other variable at run time, the 

Integration Server does not execute the link.) 

� Object and Object list variables constrained with an assigned Java class should be 

linked only to other Object and Object list variables of the same Java class or to Object 

and Object list variables of unknown type. Although Developer permits a link 

between constrained Objects with different Java classes, the run-time result is 

undefined. For more information about specifying Java classes for Objects, see “Java 

Classes for Objects” on page 421. 

� When you link between scalar and array variables, you can specify which element of 

the array variable you want to link to or from. Scalar variables are those that hold a 

single value, such as String, document, and Object. Array variables are those that hold 

multiple values, such as String list, String table, document list, and Object list. For 

example, you can link a String to the second element of a String list. Alternatively, you 

can link the second element in a String list to a String. 

� When you link between scalar and array variables and you do not specify which 

element in the array variable that you want to link to or from, Developer uses the 

default behavior to determine the value of the target variable. 

For more information about the default behavior for linking array variables, see “Default 

Pipeline Rules for Linking to and from Array Variables” on page 424. 


Examples of Structural Transformations on the Pipeline Tab 


The structural transformations you can perform by linking variables on the Pipeline tab can 

be more complex than transforming a String to a String list. For example, you can combine 

two String lists into one document list through linking. The following section explains a 

common structural transformation that you can complete via linking in the pipeline. 

Converting a String List to a Document List 

You can convert a String list to a document list using the Pipeline tab. In the following 

diagram, aList is the String list you want to convert to a document list. The variable 

documentList is the document list to which you want to copy the values contained in the 

String list. documentList has a String child aString. To convert the String list to a document 

list, link aList to aString. 

Converting a String list to a document list 

Two String lists can be combined into one document list through data mapping in the 

pipeline. For example, if in the above scenario you also had a String list variable named 

bList, and documentList had two String children named aString and bString, you could 

combine the two String lists by linking aList to aString and bList to bString. 

Converting two String lists to a document list 



Tip! You can also convert a String list to a document list (IData[ ] object) by invoking the 

built-in service pub.list:stringListToDocumentList. You can insert the service as an INVOKE step 

or as a transformer. For more information about transformers, see “What Are 

Transformers?” on page 222. For more information about built-in services, see the 

webMethods Integration Server Built-In Services Reference. 

Linking to and from Array Variables 

When you link to or from an array variable (String list, String table, document list, or 

Object list), you can specify which element in the array you want to link to or from. After 

you link the variables, you specify the index that represents the position of the element in 

the array. 

� For String lists and Object lists, you can specify the index for the list element you want 

to link. For example, you can link the third element in a String list to a String. 

� For String tables, you can specify the row and column indexes for the cells you want 

to link. For example, you can link the value of the element in the third column of the 

second row of a String table to a String. 

� For document lists, you can specify the index for the document that you want to link. 

For example, you can link the second document in a document list to a document 

variable. 

� For a variable in a document list, you can specify the index of the document that 

contains the value that you want to link to or from. For example, if the document list 

POItems contains the String ItemNumber, you can link the ItemNumber value from the 

second POItems document to a String variable. 

For example, suppose that a buyer’s address information is initially stored in a String list. 

However, the information might be easier to work with if it were stored in a document. To 

map the information in the String list to a document, create a link between the String list 

and each field in the document. Then, specify an index value for each link. In the 

following pipeline, the elements in buyerAddress String list are mapped to the address 

document. 


You can specify the index 

for the element in 

buyerAddress that you 

want to link to each field 

in address. 

You can specify an index value when linking to or from an array variable 


Note: Developer uses blue links on the Pipeline tab to indicate that properties (conditions or 

index values for arrays) have been applied to the link between variables. 

To specify the index for the element in the buyerAddress variable to be copied to the 

FirstName field, select the link between the variables, click the Indices property’s Edit button 

in the Properties panel to specify the index. 

If the source or target variable is an array, Developer displays a text box next to the 

variable (in this case, buyerAddress). If the source or target variable is not an array, 

Developer displays the words “Field not indexable” next to the variable name (in this 

case, FirstName). For example, if you want to link the first element of the buyerAddress 

variable to the FirstName field in address, type 0 in the field next to buyerAddress. (Index 

numbering in arrays begins at 0.) 

Link indices 

Indicates the index of the 

element in the buyerAddress 

String list that you want to copy 

to the FirstName field. 

Indicates the target variable is 

not an array. 


Guidelines for Linking to and from Array Variables 


When you are linking to or from an array variable, keep the following points in mind: 

� To link to or from an element in an array variable, you need to know the index for the 

element’s position in the array. Array index numbering begins at 0 (the first element in 

the array has an index of 0, the second element has an index of 1, and so on). 

� To dynamically specify the index, you can set the index to the value of a pipeline 

variable. The variable you specify must be a String. To use a pipeline variable, specify 

the variable name enclosed in percent signs (%). For example, if the pipeline contains 

the variable itemNumber that will contain the index you want to use at run time, 

specify %itemNumber% for the index. For the link to execute successfully at run time, 

the value of the variable must be a non-negative integer. 

� If you link to an array variable and specify an index that does not exist, Developer 

increases the length of the array to include the specified array index. For example, 

suppose that a String list has length 3. You can link to the String list and specify an 

index of 4; that is, you can link to the fifth position in the String list. At run time, the 

Integration Server increases the length of the String list from 3 to 5. 

� Each element in an array can be the source or target of a Link modifier; that is, each 

element in the array can be the start or end of a link. For example, if a source String list 

variable contains three elements, you can link each of the three elements to a target 

variable. 

� If the source and target variables are arrays, you can specify an index for each variable. 

For example, you can link the third element in a source String list to the fifth element 

in target String list. 

� If you do not specify an array index for an element when linking to or from arrays, the 

default behavior of the Pipeline tab will be used. For information about the default 

behavior of the Pipeline tab, see “Default Pipeline Rules for Linking to and from Array 


� If you are linking to or from a String table, you need to specify an index value for the 

row and column. 

� When you link a document or document list variable to another document or 

document list variable, the structure of the source variable determines the structure of 

the target variable. For more information, see “Linking to Document and Document 

List Variables” on page 208. 

The following procedure explains how to link to or from an array variable. 


To create a link to or from an array variable 


1 Create a link between the variables using the procedure described in “To create a link 

between variables” on page 205. 

2 Click the link that connects the variables. 

3 On the Properties panel, click the Indices property’s Edit button. Developer displays 

the Link Indices dialog box. 

4 If the source variable is an array variable, under Source, next to the source variable 

name, type the index that contains the value you want to link. 

5 If the target variable is an array variable, under Destination, next to the destination 

variable name, type the index to which you want to link the source value. 

6 Click OK. 

Note: At run time, the link (copy) fails if the source array index contains a null value or if 

you specify an invalid source or target index (such as a letter or non-numeric character). 

The Integration Server generates journal log messages (at debug level 6 or higher) when 

links to or from array variables fail. 

Deleting Links Between Variables 

Use the following procedure to delete the link created between variables. When you 

delete the link, the variables are no longer linked. Developer also deletes any properties 

you applied to the link. 

To delete a link between variables 

1 On the Pipeline tab, select the link that you want to delete. 


Tip! You can also delete a link by selecting it and then clicking on the Pipeline tab 

toolbar or pressing the DELETE key. 

Applying Conditions to Links Between Variables 

You can place conditions on the links you draw between variables. At run time, 

webMethods Integration Server evaluates the condition and executes the link (copies the 

value) only if the condition evaluates to true. 

A condition consists of one or more expressions that you write using the syntax that 

Developer provides. An expression can check for the existence of a variable in the 


Use the Properties 

panel to view or create 

a condition for the link. 


pipeline, check for the value of a variable, or compare a variable to another variable. For 

example, in the following service, you might want to link the BuyersTotal variable in 

Pipeline In to the OrderTotal variable in Service In only if the BuyersTotal has a value that is 

not null. After you connect the two variables with the Link modifier, you would edit the 

properties and add the condition that needs to be true. 

A blue link indicates that a condition is applied to the link connecting the variables 

Developer uses a blue link on the Pipeline tab to indicate that properties (that is, conditions 

or index values for arrays) have been applied to a link between variables. 

Note: You cannot add conditions to the links between implicitly linked variables. 

Linking Multiple Source Variables to a Target Variable 

By applying conditions to the links between variables, you can link more than one source 

variable to the same target variable. When you draw more than one link to the same target 

variable, at most, only one of the conditions you apply to the links can be true at run time. 

The conditions must be mutually exclusive. 

At run time, webMethods Integration Server executes all conditional links whose 

conditions evaluate to true. If more than one conditional link to the same target variable 

evaluates to true, the value of the target variable will be the result of whichever link 

executes last. Because the order in which links are executed at run time is not guaranteed, 

the final value of the target variable may vary. 



Tip! If the conditions for links to the same target variable are not mutually exclusive, 

consider using a flow service containing a BRANCH step instead. In BRANCH steps, 

child steps are evaluated in a top to bottom sequence. webMethods Integration Server 

executes the first child step that evaluates to true and skips the remaining child steps. For 

more information about the BRANCH step, see “The BRANCH Step” on page 168. 

To apply a condition to the link between variables 

1 Create a link between the variables using the procedure described in “To create a link 

between variables” on page 205. 

2 Click the link (black line) that connects the variables. 

3 On the Properties panel, set the Evaluate copy condition property to True. 

4 In the Copy condition property text box, type the condition you want to place on the 

link. 

For information about the syntax used in conditions, see Appendix D, “Conditional 

Expressions”. 

Important! When drawing more than one link to the same target variable, make sure that 

the conditions assigned to each link are mutually exclusive. 

Note: You can temporarily disable the condition placed on a link. For more information, 

see “Disabling a Condition Placed on a Link Between Variables” on page 301. 

Assigning Values to Pipeline Variables 

The Set Value modifier allows you to assign values to variables in Service In or Pipeline 

Out. You use it to explicitly “hard code” a specific value in a variable. You can also use it to 

assign a default value to a variable. 

By attaching a Set Value modifier to a variable, you instruct the server to write a 

specific value to that variable at run time. This action occurs just before the selected 

service is executed (if you attach the modifier to a variable in Service In) or immediately 

after the selected service is executed (if you attach the modifier to a variable in Pipeline 

Out). 


You use the Set 

Value modifier to 

assign a value to a 

variable. 

Specify the value that 

you want the server to 

assign to this variable at 

run time. 

Hardcoding the value of a variable 


To view (or change) the value that is assigned to the Set Value modifier, double-click the 

icon next to the variable’s name to open the Input For dialog box. 

Input For dialog box 

Assigning a Default Value to a Variable 

One common use of the Set Value modifier is to specify a default value for a variable (that is, 

a value that is only assigned if the variable is null at run time). To use the Set Value 

modifier in this way, disable the Overwrite pipeline value check box in the Input For dialog 

box. This instructs the server to use the specified value only when the selected variable is 

null. 

Note: If a variable to which you assigned a default value is implicitly linked to another 

variable in the pipeline, Developer displays a gray link on the Pipeline tab connecting the 

variables beneath the icon. 


Enclose the variable 

name in % symbols... 

...and the select the 

variable-substitution 

option. 

Initializing Variables in a Flow Service 


You can use the Set Value modifier with the MAP step to hard code an initial set of input 

values in a flow service. To use it in this way, insert the MAP at the beginning of your flow, 

and then use the Set Value modifier to assign values to the appropriate variables in Pipeline 

Out. 

Referencing Other Variables 

In addition to assigning a literal value to a variable, the Set Value modifier lets you assign 

the value of another String variable to a String variable. (You might do this if you wanted 

to derive the default value from a variable in the pipeline at run time, for example.) 

To specify a variable name with the Set Value modifier, enclose the name of that variable 

between % symbols and then enable the Perform variable substitution option. This option 

instructs the server to interpret your value as a variable reference rather than a literal 

value. 

Referencing variables 

You can also format String values by specifying one or more pipeline variables in 

conjunction with a literal value. For example, if you specified (%areaCode%) %Phone%, 

the resulting string would be formatted to include the parentheses and space. If you 

specified %firstName% %initial%. %lastName% , the period and spacing would be 

included in the value. 

Setting a Value for a Pipeline Variable 

Keep the following points in mind when assigning a value to a pipeline variable: 

� You can only assign values to variables that are in Service In or Pipeline Out. 

� If the Service In or Pipeline Out variable is already the target for a Link modifier, you 

cannot use the Set Value modifier to assign a value to the variable. 

� You can mix literal values and pipeline variables when assigning values to String 

variables. 

� You cannot assign a value to a recursive IS document type (a document type that 

contains a document reference to itself). 



� When you set values for constrained Objects, Developer automatically validates the 

values. If the value is not of the type specified by the object constraint, Developer 

displays a message identifying the variable and the expected type. 

� You cannot set values for unconstrained Objects (Objects of unknown type) or for 

Objects constrained as a byte [ ]. 

To assign a value to a variable in the pipeline 

1 In the editor, select the INVOKE or MAP step containing the variable you want to 

alter. 


3 Select the variable to which you want to assign a value. 

4 Click on the toolbar. 

5 In the Input For dialog box, specify the value you want to assign to this variable. 

� If you want to assign a literal value to the variable, type that value. The value 

must be of the same data type as the variable. 

� If you want to derive the value from a String variable in the pipeline, type the 

name of that variable enclosed in % symbols (for example, %Phone%). Then select 

the Perform variable substitution check box. 

6 If you want the server to use the specified value only if the variable does not contain a 

value at run time, clear the Overwrite pipeline value check box. (If you select this check 

box, the server will always apply the specified value.) 

Copying Set Values Between Variables 

You can copy the set value assigned to a variable to other variables of the same data type 

in Service In or Pipeline Out. When you copy set values from one pipeline variable to 

another, keep the following points in mind: 

� You can only copy and paste set values between variables of the same data type. For 

example, you can only copy the set value assigned to a String variable to another 

String variable. 

� You can only copy and paste set values between variables if the target variable has the 

same structure as the source variable or has no defined structure. For example, you 

can copy the set value of a String list variable with length 3 to another String list 

variable only if the target String list also has length 3 or has an undefined length (no 

defined structure). 

� If you are copying a set value between document variables, the source document 

variable and the target document variable must have the same structure or the target 

document variable must have no structure defined. For example, if the source 



document variable contains three String variables named City, State, and Zip as 

children, the target document variable must have three String variables named City, 

State, and Zip as children. 

To copy a set value 

1 In the editor, select the INVOKE or MAP step containing the variable with the value 

you want to copy and paste. 


3 Select the you want to copy. 

4 Right-click and select Copy. 

5 Select the variable or variables to which you want to assign the copied value, 

right-click and select Paste. 

Note: You can only copy and paste values for variables that are in Service In or Pipeline Out. 

Note: You can only paste the set value if the target variable is the same data type as the 

source variable and if the target variable has either an identical structure to the source 

variable or has no defined structure. 

Dropping Variables from the Pipeline 

The Drop pipeline modifier allows you to remove a variable from Pipeline In or Pipeline 

Out. You can use it to eliminate pipeline variables that are not used by subsequent services 

in a flow. Dropping unneeded variables reduces the size of the pipeline at run time and 

reduces the length and complexity of the Pipeline In and Pipeline Out displays (this can make 

the Pipeline tab much easier to use when you are working with a complex flow). 

Important! Once you drop a variable from the pipeline, it is no longer available to 

subsequent services in the flow. Do not use the Drop modifier unless you are sure the 

variable is not used by services invoked after the point where you drop it. 

At run time, the server removes a dropped variable from the pipeline just before it 

executes the selected service (if you attach the Drop modifier to a variable in Pipeline In) or 

immediately after it executes the selected service (if you attach the Drop modifier to a 

variable in Pipeline Out). 

If you drop a linked variable from Pipeline In, the server executes the Link modifier before it 

drops the variable. The server does not link a null value to the destination variable. 


To drop a variable from the pipeline 


1 In the editor, select the INVOKE or MAP step whose pipeline variables you want to 

drop. 


3 Select the variable that you want to drop. 

4 Click on the toolbar. 

Note: You can only drop variables from Pipeline In and Pipeline Out. In a MAP step, you can 

only drop variables from Pipeline In. 

Adding Variables with the Pipeline Tab 

You can use the Pipeline tab to add variables that were not declared as input or output 

parameters for the flow service itself or any of its constituent services. You can use it to 

add variables that were omitted from a service’s input or output parameters or create 

temporary variables for use within the flow. (For example, you might attach a variable to 

each of the children in a BRANCH step to mark the path taken by the service at run time.) 

Variables that you create using the Pipeline tab can be used just like any declared variable 

in the flow. 

Important! If you create a new variable in a flow, you must immediately do one of the 

following: 

– Link a variable to it 

– Assign a value to it 

– Drop it 

If you do not take one of these steps, Developer automatically clears it from the Pipeline 

tab. 

Note: You might want to drop a variable immediately after adding it if a service produces a 

variable that is not declared in the service input or output parameters. The variable will 

not appear on the Pipeline tab if it is not an input or output parameter. By adding and then 

immediately dropping the variable, you can delete the variable if it does exist in the 

pipeline. 


To add a variable to the pipeline 


1 In the editor, select the INVOKE or MAP step that represents the stage of the pipeline 

at which you want to add a new variable. 


3 Select the point where you want to add the new variable. 

4 Click and select the type of variable that you want to create. 

5 Type the name of the variable and press ENTER. 

6 If the variable is a document or a document list, repeat steps 4 and 5 to define its 

member variables. Then use to indent each member variable beneath the 

document or document list variable. 

7 Assign one of the pipeline modifiers to the new variable (Link, Drop, or Set Value). (If 

you do not assign a modifier to the variable, Developer considers it extraneous to the 

flow and automatically clears the variable when it refreshes the Pipeline tab.) 

Working with Transformers 

Note: In an INVOKE step, you can add a new variable to Pipeline In, Service In, Service 

Out, or Pipeline Out. In a MAP step, you can only add new variables in Pipeline Out. 

By linking variables to each other on the Pipeline tab, you can accomplish name 

transformations and structural transformations. However, to perform value 

transformations you must execute some code or logic (that is, you must invoke a service). 

Developer provides two ways for you to invoke services: You can insert INVOKE steps or 

you can insert transformers onto the Pipeline tab. 

What Are Transformers? 

Transformers are the services you use to accomplish value transformations on the Pipeline 

tab. You can only insert a transformer into a MAP step. You can use any service as a 

transformer. This includes any Java, C or flow service that you create and any built-in 

services in WmPublic, such as the pub.date.getCurrentDateString and the pub.string.concat 

services. By using transformers, you can invoke multiple services (and perform multiple 

value transformations) in a single flow step. 

Note: Services that you insert using the INVOKE step might also perform value 

transformations. However, only transformers can accomplish multiple value 

transformations in a single flow step. 



You can think of transformers as a series of INVOKE steps embedded in a MAP step. And 

like INVOKE steps, when you insert a transformer, you need to create links between 

pipeline variables and the transformer. You can also set properties for the transformer and 

validate the input and/or output of the transformer. Because transformers are contained 

within a MAP step, they do not appear as a separate flow step in the editor. 

Transformers are well suited for use when mapping data from one document format to 

another. When you map data between formats, you usually need to perform several name, 

structure, and value transformations. By using transformers, the flow service in which 

you map data between formats could potentially consist of a single MAP step in where 

transformers and links between variables handle all of the data transformations. In this 

way, you could see your entire document-to-document mapping in a single view. 

Tip! You can create a flow service that uses transformers to convert data between 

document formats (such as an IDOC to an XML document or RosettaNet PIP to a 

proprietary format). You could then invoke this service in other flow services each time 

you need to convert between the specific document formats before you begin processing 

data. 

MAP step with transformers 

Note: In a MAP step, Developer only displays the links between pipeline variables and 

transformers. Developer does not display any implicit linking for a MAP step. 


Using Built-in Services as Transformers 


Any service in the Navigation panel can be used as a transformer. webMethods provides 

several built-in services specifically designed to translate values between formats. These 

services can be found in the following folders in the WmPublic package: 

This folder… Contains services to… 

pub.date Transform time and date information from one format to another. 

pub.document Transform documents to and from document lists and XML 

values. 

pub.list Transform a String list to a document list (IData[ ] object) and 

append items to a document list (IData[ ] object) or a String list. 

pub.math Perform simple arithmetic calculations (add, subtract, multiply, 

and divide) on integers and decimals contained in string variables. 

pub.string Transform string values in various ways (for example, pad, 

substring, concat, replace through a lookup table). 

For more information about built-in services, see the webMethods Integration Server Built-In 


Inserting a Transformer into a MAP Step 

When you insert a transformer, you are essentially inserting an INVOKE step into a MAP 

step. When inserting transformers, keep the following points in mind: 

� Transformers can only be inserted in a MAP step. 

� Any service can be used as a transformer, including flow services, C services, and Java 

services. 

� The transformers you insert into a MAP step operate on the same set of pipeline data. 

� The output of one transformer cannot be used as the input of another transformer in 

the same MAP step. 

� Transformers in a MAP step are independent of each other and do not execute in a 

specific order. When inserting transformers, assume that webMethods Integration 

Server concurrently executes the transformers at run time. 

To insert a transformer 

1 In the editor, select the MAP step in which you want to insert a transformer. 

2 Click the Transformers area on the Pipeline tab. 



3 Click on the Pipeline tab toolbar and then select the service you want to invoke. 

If the service you want to insert does not appear in the list, select Browse to select the 

service from the Navigation panel. The transformer appears under Transformers on the 

Pipeline tab. 

4 Select the transformer and, in the Properties panel, set its properties: 


Service The fully qualified name of the service that will be invoked at 

run time as a transformer. When you insert a transformer, 

Developer automatically assigns the name of that service to 

the service property. If you want to change the service that is 

invoked by a transformer, specify the service’s fully qualified 

name in the folderName:serviceName format or click to 

select a service from a list. 

Validate input Whether or not you want to validate the input to the 

transformer against the signature of the service. Select True to 

validate the input of the transformer. Select False if you do not 

want to validate the input of the transformer. 

For information about validating transformers, see “Validating 

Input and Output for Transformers” on page 229. 

Validate output Whether or not you want to validate the output of the 

transformer against the signature of the service. Select True to 

validate the output of the transformer. Select False if you do 

not want to validate the output of the transformer. 

5 Click OK. 

For information about validating transformers, see “Validating 

Input and Output for Transformers” on page 229. 

For information about debugging transformers, see “Debugging Transformers” on 

page 232. 

Tip! When you expand a transformer in the Transformers area of the Pipeline tab, you can see 

the Service In variables and the Service Out variables and all of the explicit links between the 

transformer and the pipeline. You might find it easier to link transformer variables when 

you are zoomed in on the transformer. 


Linking Variables to a Transformer 


When you map data to and from a transformer, you create links between the pipeline 

variables and the transformer. Keep the following points in mind when you create links 

between pipeline and transformer variables: 

� Developer does not implicitly link pipeline variables to the input or output variables 

of a transformer. Even if the pipeline variables have the same name and data type as 

the transformer variables, no implicit linking occurs. You need to explicitly link 

pipeline variables to the input and output variables of a transformer. 

� Output for a transformer is not automatically added to the pipeline. If you want the 

output of a transformer to appear in the pipeline, you need to explicitly link the 

output variable to a Pipeline Out variable. If you do not link the output variable to a 

Pipeline Out variable, the output variable does not appear in the pipeline. 

� If you do not link any output variables or the transformer does not have any declared 

output variables, the transformer service will not run. 

� The transformers you insert into a single MAP step act on the same set of pipeline 

data. 

To provide the cleanest and simplest view when working with transformers, the Pipeline 

tab only displays one link between the transformer and a Pipeline In variable and one link 

between the transformer and a Pipeline Out variable. (The Pipeline tab displays the links 

between the transformer and the highest positioned Pipeline In variable and Pipeline Out 

variable to which the transformer is linked.) 

To create a link between a pipeline variable and a transformer 

1 To create a link between a Pipeline In variable and a transformer variable, do the 

following: 

a In Pipeline In, select the variable you want to use as input to the transformer and 

drag your mouse to the transformer. 

b In the Link To list, select the transformer variable to which you want to link the 

Pipeline In variable. 

Once you link a transformer input variable to a Pipeline In variable, Developer 

displays the phrase “has already been chosen” next to the transformer variable in 

the Link To list. 

c Repeat steps a and b for each transformer input variable you want to link to a 

pipeline variable. 



Note: You can assign a value to a transformer input variable using the Set Value 

modifier . To assign an input value to a transformer, first expand the transformer 

by double-clicking the transformer name, by clicking Compose�Expand, or by clicking 

next to the transformer. 

2 To create a link between a transformer output variable and a Pipeline Out variable, do 

the following: 

a Select the transformer and drag your mouse to the variable in Pipeline Out to which 

you want to link the transformer variable. 

b In the Link From list, select the transformer variable that you want to link to the 

selected Pipeline Out variable. 

c Repeat steps a and b for each output variable produced by the transformer. 

You can link a transformer output variable to more than one Pipeline Out variable. 

Important! Developer does not automatically add the output of a transformer to the 

pipeline. If you want the output of a transformer to appear in the pipeline after the 

transformer executes, you need to explicitly link the output variable to a variable in 

Pipeline Out. 

Important! If you do not link any output variables or the transformer does not have any 

output variables, the transformer will not execute. 

Transformer Movement 

When you link to and from a selected transformer, it moves up and down in the 

Transformers column. This movement or “jumping” is by design to help minimize the 

distance between the transformer and the variable you are linking it to. 

Transformers exhibit the following behavior or movement: 

� When a transformer is selected and you select a variable in Pipeline In or Pipeline Out, 

the transformer “jumps” or moves up or down in the Transformers column so that it is 

directly across from the selected pipeline variable. 

� When you finish linking a transformer and it is no longer selected, Developer 

“anchors” or aligns the transformer next to the highest Pipeline Out variable it is linked 

to. 

To stop the transformer from jumping, click the transformer again or click in the empty 

areas of the Pipeline tab. 



Note: To expand your view of the Pipeline tab, drag the movable border above the tab. The 

Pipeline tab expands to fit in the Developer window. 

Transformers and Array Variables 

When creating links between pipeline variables and transformers, differences in 

dimensionality for the source and target variables may cause an exception. If the 

dimensionality of the target variable is greater than the dimensionality of the source 

variable, an exception will not be thrown. However, if the dimension of the source 

variable is greater than the dimension of the target variable, an exception will occur. 

What Is Dimensionality? 

Dimensionality refers to the number of arrays to which a variable belongs. For example, 

the dimensionality of a single String is 0, that of a single String list or document list is 1, 

and that of a single String table is 2. A String that is a child of a document list has a 

dimensionality of 1. A String list that is a child of a document list has a dimensionality 

of 2. 

Example 

In the following example, the unitPrice variable cannot be linked to num1 because the 

unitPrice variable has a dimensionality of 1 ( string (0) + document list (1) = 1) and num1 

has a dimension of 0. 

unitPrice cannot be linked to num1 because of dimensionality differences 


Solution 

To solve this, you can either: 


� Change the service invoked by the transformer to accept arrays as data, or 

� Create a flow service in which a LOOP step loops over the array variable. Then, (in the 

same flow service) invoke the service you originally wanted to use as a transformer, 

and make that INVOKE step a child of the LOOP. Finally, insert the resulting flow 

service as a transformer in the MAP. 

Of the two options, changing the service to accept arrays as data results in faster execution 

of flow services. 

Validating Input and Output for Transformers 

As with any service you insert using an INVOKE, you can validate the inputs and outputs 

of the transformer service before and/or after it executes. To indicate that you want to 

validate a transformer’s inputs and outputs, you change the properties of the transformer. 

You do not have to use validation for all of the transformers you insert into a MAP step. 

When the server validates a transformer’s inputs and outputs at run time, it validates the 

transformer against the input and output parameters of the invoked service. To view the 

input and output parameters of the invoked service, open the service and then click the 

service’s Input/Output tab. The variables on the input and output sides of the tab represent 

the declared parameters for the service. To view the constraints placed on a variable, click 

the variable and view its Constraints properties in the Properties panel. 

Note: If the Validate input and/or Validate output properties of the invoked service are set to 

True, the input and/or output for the service will automatically be validated every time the 

service is executed. If you set up validation via the properties for a transformer when it is 

already set up for validation via the service’s Properties panel, then you are performing 

validation twice. This can slow down the execution of a transformer and, ultimately, the 

flow service. 

To validate the input and output of a transformer 

1 In the editor, select the MAP step containing the transformer you want to validate. 


3 Under Transformers, select the transformer for which you want to validate input or 

output. 

4 On the Properties panel, for the Validate input property, select True if you want to 

validate the input to the transformer against the input parameters of the invoked 

service. 



5 For the Validate output property, select True if you want to validate the output of the 

transformer against the output parameters of the invoked service. 

6 Click OK. 

Copying Transformers 

You may want to use the same transformer more than once in a MAP step. For example, 

you might want to convert all the dates in a purchase order to the same format. Instead of 

using the button to locate and select the service, you can copy and paste the 

transformer service. 

You can also copy transformers between MAP steps in the same flow or MAP steps in 

different flow services. 

Important! Copying a transformer does not copy the links between transformer variables 

and pipeline variables or any values you might have assigned to transformer variables 

using the Set Value modifier. 

To copy a transformer 

1 In the editor, select the MAP step containing the transformer service you want to copy. 


3 Under Transformers, select the transformer service you want to copy. Right-click the 

transformer and then select Copy. 

4 To paste the transformer, click anywhere under Transformers. Right-click and select 

Paste. 

5 Link the input and output variables of the transformer using the procedures 

described in “Linking Variables to a Transformer” on page 226. 

Expanding Transformers 

You might find it easier to create links to transformers when you expand the transformer. 

When you expand a transformer, you can see the Service In and the Service Out variables for 

the transformer and all of the links between the pipeline and the transformer variables. 


Pipeline tab with an expanded transformer 


When you expand a transformer, you can only perform actions for that transformer, for 

example, you can only link variables or set properties for the expanded transformer. Other 

transformers and links to other transformers remain hidden until you collapse the 

transformer. 

Note: If you expand a transformer, you can use the Set Value modifier to assign a value to a 

variable in Service In. 

To expand and collapse the contents of a transformer 

� To expand the contents of a transformer, click Compose�Expand. 

� To collapse the contents of a transformer, click Compose�Collapse. 

Tip! You can also expand/collapse a transformer by double-clicking it. 

Note: If Integration Server displays a message stating that the transformer cannot be 

found, then the service invoked by the transformer has been renamed, moved, or 

deleted. You must use the transformer properties to rename the transformer. See the 

following section for more information. 

Renaming Transformers 

If Integration Server displays the message “Transformer not found” when you try to 

expand a transformer or when you point the mouse to the transformer, then the service 

referenced by the transformer has been renamed, moved, or deleted. You need to change 



the Service property of the transformer so that the transformer points to the moved, or 

renamed service. 

If the service referenced by the transformer has been deleted, you may want to delete the 

transformer. 

Tip! You can enable safeguards so that you do not inadvertently affect or break other 

services when you move, rename, or delete a service. For more information, see 

“Specifying Dependency Checking Safeguards” on page 47. 

To rename a transformer 

1 Use the Navigation panel to determine the new name or location of the service called 

by the transformer. 

2 Open the flow service containing the transformer you want to rename. 

3 In the editor, select the MAP step containing the transformer. Then, on the Pipeline tab, 

select the transformer you want to rename. 

4 In the Service property on the Properties panel, delete the old name and type in the 

service’s new fully qualified name in the folderName:serviceName format, or click to 

select a service from a list. 

Debugging Transformers 

When you test and debug a flow service, you can use the following testing and debugging 

techniques with transformers: 

� Step into a MAP step and step through the execution of each transformer. For more 

information about stepping into and out of a MAP step, see “Using the Step Tools 

with a MAP Step” on page 294. 

� Set a breakpoint on a transformer so that service execution stops when the 

transformer is encountered. For more information about setting breakpoints, see 

“Setting Breakpoints” on page 295. 

� Disable a transformer so that it does not execute at run time. For more information 

about disabling transformers, see “Disabling Transformers” on page 299. 


Chapter 9. Creating IS Schemas, IS Document Types, and 

Specifications 

� Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

� Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

� Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 


Creating an IS Schema 

9. Creating IS Schemas, IS Document Types, and Specifications 

An IS schema is a “free-standing” element in the Navigation panel that acts as the 

blueprint or model against which you validate an XML document. The IS schema 

provides a formal description of the structure and content for a valid instance document 

(the XML document). The formal description is created through the specification of 

constraints. An IS schema can contain the following types of constraints: 

� Structural constraints in an IS schema describe the elements, attributes, and types that 

appear in a valid instance document. For example, an IS schema for a purchase order 

might specify that a valid element must consist of the , 

, , , and elements in that order. 

� Content constraints in an IS schema describe the type of information that elements and 

attributes can contain in a valid instance document. For example, the 

element might be required to contain a value that is a positive integer. 

During data validation, the validation engine in webMethods Integration Server compares 

the elements and attributes in the instance document with the structural and content 

constraints described for those elements and attributes in the IS schema.The validation 

engine considers the instance document to be valid when it complies with the structural 

and content constraints described in the IS schema. For more information about data 

validation, see Chapter 10, “Performing Data Validation”. 

You can create IS schemas from an XML Schema, a DTD (Document Type Definition), or 

an XML document that references an existing DTD. For information about creating IS 

schemas, see “Creating an IS Schema” on page 239. 

What Does an IS Schema Look Like? 

The appearance and content of an IS schema depends on whether you generate an IS 

schema from an XML Schema or a DTD. For example, if you create an IS schema from an 

XML Schema, the resulting IS schema displays type definitions, element declarations, and 

attribute declarations. If you create an IS schema from a DTD, the resulting IS schema 

displays element type declarations. 

When you select an IS schema in the Navigation panel, Developer displays the contents of 

the IS schema in the editor. The schema editor is divided into two areas: the schema 

browser on the left and the schema details area on the right. Above these areas, the editor 

identifies the target namespace for the IS schema. 


Specifies the target 

namespace to which 

the schema belongs. 

Select a component in 

the schema browser... 

...to view and/or edit the 

component in the 

schema details area. 

Schema editor 

Schema Browser 


The schema browser displays the components of an IS schema in a format that mirrors the 

structure and content of the source file. The schema browser groups the global element 

declarations, attribute declarations, simple type definitions, and complex type definitions 

from the source file under the top-level headings ELEMENTS, ATTRIBUTES, SIMPLE 

TYPES, and COMPLEX TYPES. For example, the ELEMENTS heading contains all of the 

global element declarations from the XML Schema or the DTD. 

If the source file does not contain one of these global components, the corresponding 

heading is absent. For example, if you create an IS schema from an XML Schema that does 

not contain any global attribute declarations, the schema browser does not display the 

ATTRIBUTES heading. An IS schema created from a DTD never displays the SIMPLE 

TYPES or COMPLEX TYPES headings because DTDs do not contain type definitions. 

Note: A DTD does contain attribute declarations. However, the schema browser does not 

display the ATTRIBUTES heading for IS schemas generated from DTDs. This is because 

an attribute declaration in a DTD associates the attribute with an element type. 

Accordingly, the schema browser displays attributes as children of the element type 

declaration to which they are assigned. For more information, see the webMethods 

Integration Server Schema Reference. 

The schema browser uses unique symbols to represent the components of the IS schema. 

Each of these symbols relates to a component of an XML Schema or a DTD. The following 

table identifies the symbol for each component that can appear in an IS schema. 



Note: In the following table, global refers to elements, attributes, and types declared or 

defined as immediate children of the element in an XML Schema. All element 

type declarations in a DTD are considered global declarations. 

Symbol Description 

Element declaration. An element declaration associates an element name 

with a type definition. This symbol corresponds to the 

declaration in an XML Schema and the ELEMENT declaration in a DTD. 

Element reference. An element reference is a reference from an element 

declaration in a content specification to a globally declared element. 

In an IS schema generated from an XML Schema, this symbol corresponds 

to the ref="globalElementName" attribute in an declaration. 

In an IS schema generated from DTD, this symbol appears next to an 

element that is a child of another element. The parent element has only 

element content. 

Any element declaration. In XML Schema, an element declaration is a 

wildcard declaration used as a placeholder for one or more undeclared 

elements in an instance document. 

In a DTD, an element declared to be of type ANY can contain any 

well-formed XML. This symbol corresponds to an element declared to be 

of type ANY. 

Because an element declaration does not have a name, the schema 

browser uses 'Any' as the name of the element. 

Attribute declaration. An attribute declaration associates an attribute name 

with a simple type definition. This symbol corresponds to the XML 

Schema declaration or the attribute in a DTD ATTLIST 

declaration. 

Attribute reference. An attribute reference is a reference from a complex type 

definition to a globally declared attribute. This symbol corresponds to the 

ref="globalAttributeName" attribute in an attribute declaration. 

DTDs do not have attribute references. Consequently, attribute references 

do not appear in IS schemas generated from DTDs. 

Any attribute declaration. An any attribute declaration is a wildcard 

declaration used as a placeholder for undeclared attributes in an instance 

document. This symbol corresponds to the declaration in 

an XML Schema. 

Because an declaration does not specify an attribute 

name, the schema browser uses 'Any' as the name of the attribute. 


Symbol Description 


Simple type definition. A simple type definition specifies the data type for a 

text-only element or an attribute. Unlike complex type definitions, simple 

type definitions cannot carry attributes. This symbol corresponds to the 

element in an XML Schema. 

If the simple type definition is unnamed (an anonymous type), the schema 

browser displays 'Anonymous' as the name of the simple type definition. 

Complex type definition. A complex type definition defines the structure and 

content for elements of complex type. (Elements of complex type can 

contain child elements and carry attributes.) This symbol corresponds to 

the element in an XML Schema. 

If the complex type definition is unnamed (an anonymous type), the 

schema browser displays 'Anonymous' as the name of the complex type 

definition. 

Sequence content model. A sequence content model specifies that the child 

elements in the instance document must appear in the same order in which 

they are declared in the content model. This symbol corresponds to the 

compositor in an XML Schema or a sequence list in an element 

type declaration in a DTD. 

Choice content model. A choice content model specifies that only one of the 

child elements in the content model can appear in the instance document. 

This symbol corresponds to the compositor in an XML Schema 

or a choice list in a DTD element type declaration. 

All content model. An all content model specifies that child elements can 

appear once, or not at all, and in any order in the instance document. This 

symbol corresponds to the compositor in an XML Schema. 

Mixed content. Elements that contain mixed content allow character data to 

be interspersed with child elements. This symbol corresponds to the 

mixed="true" attribute in an XML Schema complex type definition or a 

DTD element list in which the first item is #PCDATA. 

Empty content. In an XML Schema, an element has empty content when its 

associated complex type definition does not contain any element 

declarations. An element with empty content may still carry attributes. 

In a DTD, an element has empty content when it is declared to be of type 

EMPTY. 


If you select an 

element declaration... 

... the schema details 

area displays information 

about that element. 

Schema Details Area 


The schema details area displays information that you use to examine and edit the 

selected component in the schema browser. The contents of the schema details area vary 

depending on what component you select. For example, when you select a globally 

declared element of complex type, the schema details area looks like the following. 

Schema details area for a global element declaration of complex type 


If you select a simple 

type definition... 

... the schema details 

area displays fields for 

viewing/editing the 

simple type. 


When you select a simple type definition, the schema details area looks like the following: 

Schema details area for a simple type definition 

Creating an IS Schema 

In Developer, you can create IS schemas from XML Schema definitions, DTDs, and XML 

documents that reference an existing DTD. The resulting IS schema contains all of the 

defined types, declared elements, and declared attributes from the source file. 

Note: The actual work of creating an IS schema is performed by the schema processor. The 

schema processor is the subsystem of the webMethods Integration Server that compiles an 

IS schema from a source file. 

Note: You can find sample XML Schema definitions in the following directory: 

webMethods6\Developer\samples\xml\xsd. You can also find XML Schema definitions 

and DTDs on the Web sites for these groups: (www.w3c.org and 

www.openapplications.org). 


To create an IS schema 


2 In the New dialog box, select Schema, and then click Next. 


3 In the New Schema dialog box, next to Folder, select the folder where you want to save 

the IS schema. 

4 In the Name field, type a name for the IS schema using any combination of letters, 

numbers, and the underscore character. Click Next. 

Important! If you specify a name that uses a reserved word or character, webMethods 

Integration Server displays an error message. When this happens, use a different 

name or try adding a letter or number to the name to make it valid. For more 

information about restricted characters for packages, folders, and elements, see 

“About Element Names” on page 45. 

5 In the New Schema dialog box, select one of the following to specify the source for the 

IS schema. 

Specify... To... 

XML Create an IS schema based on an existing DTD referenced by an 

XML document. 

DTD Create an IS schema based on a DTD. 

XML Schema Create an IS schema based on an XML Schema definition. 

Important! You can create an IS schema from an XML document only if the XML 

document references an existing DTD. 

6 Click Next. 

7 In the Enter the URL or select a local file box, do one of the following: 

� If you want to base the IS schema on an XML document, DTD, or XML Schema 

definition that resides on the Internet, type the URL of the resource. (The URL you 

specify must begin with http: or https:.) 

� If you want to base the IS schema on an XML document, DTD, or XML Schema 

definition that resides on your local file system, type the path and file name, or 

click to navigate to and select the file. 

8 Click Finish. Developer generates the IS schema using the document you specified and 

displays it in the editor. 



Note: You might receive errors or warnings when creating an IS schema from an XML 

Schema definition or DTD. For more information about these errors and warnings, see 

Appendix G, “Validation Errors and Exceptions”. 

Note: When creating an IS schema from an XML Schema definition, Developer validates 

the schema and does not create the IS schema if the XML Schema definition is not valid. 

For more information, see “IS Schema Generation Errors and Warnings” on page 486. 

Creating IS Schemas from XML Schemas that Reference Other Schemas 

A schema author can insert the elements, attributes, and type definitions from another 

schema into the schema they are creating. A schema author might do this to break up a 

large XML Schema into several small, more reusable XML Schemas. When you generate 

an IS schema from an XML Schema that references another schema, the schema processor 

either includes all of the schema components in a single IS schema, creates multiple IS 

schemas, or creates no IS schema at all. The behavior of the schema processor depends on 

the mechanism the source XML Schema uses to reference the other schema. The following 

mechanisms can be used to reference an external schema: 

� Include. When you generate an IS schema from an XML Schema that uses 

to include the contents of an external schema in the same namespace, the resulting IS 

schema contains all of the defined types, declared elements, and declared attributes 

from the source schema and the external schema. If the including, or root, XML 

Schema references an external schema that does not contain a target namespace 

declaration, the external schema assumes the target namespace of the root schema. 

� Import. When you generate an IS schema from an XML Schema that contains an 

element to import the contents of an external schema in a different 

namespace, the schema processor creates one IS schema per namespace. For example, 

if the source XML Schema imports two XML Schemas from the same namespace, the 

schema processor creates an IS schema for the source XML Schema and then a second 

IS schema that includes the components from the two imported XML schemas. The 

schema processor assigns each imported schema the name that you specify and 

appends an underscore and a number to each name. For example, if you create an IS 

schema named “mySchema” from mySchema.xsd, the schema processor generates an 

IS schema named “mySchema_2” for the imported XML Schema. 

� Redefine. Schema authors can also use to include and then redefine type 

definitions, model groups, and attribute groups from an external XML Schema in the 

same namespace. The schema processor in Integration Server does not support 

at this time. The schema processor will not generate an IS schema for an 

XML Schema that contains a mechanism. When the schema processor 

encounters a mechanism in an XML Schema, Developer displays the 

following message: 

Detected use of "redefine" in {XML Schema Name}. webMethods Integration Server 

does not support "redefine". 


The string simple type 

cannot be edited. 

This globally defined 

simple type can be 

edited. 

This simple type cannot 

be edited because it 

refers to a globally 

defined simple type. 

This anonymous simple 

type can be edited. 

Editing a Simple Type in an IS Schema 


You can modify a simple type definition in an IS schema without editing the source XML 

Schema definition. You edit a simple type by adding or changing the value of one or more 

constraining facets applied to the simple type. For example, you can modify a simple type 

by adding an enumerated value, a pattern constraint, or changing the length constraint. 

Editing the simple type through Developer is an alternative to editing the source XML 

Schema definition and regenerating the IS schema. 

You can edit any of the globally defined simple types (those that appear under the 

SIMPLE TYPES heading) or anonymous simple types (those defined as part of an element 

or attribute declaration.) A named simple type that appears as a child of an element or 

attribute in the schema browser cannot be edited. (These simple types are global simple 

types used to define the element or attribute they appear under.) The following 

illustration identifies the simple type definitions that you can and cannot edit. 

Editable simple type definitions in an IS schema 

When modifying a simple type definition, keep the following points in mind: 

� Changes to a simple type definition affect the elements and attributes for which the 

simple type is the defined type. For example, if the attribute partNum is defined to be 

of type SKU, changes to the SKU simple type definition affect the partNum attribute. 



� Changes to a global simple type definition in an IS schema do not affect simple types 

derived from the global simple type; that is, the changes are not propagated to the 

derived types in the IS schema. 

� Simple types in an IS schema can be used as content constraints for fields in pipeline 

validation. Consequently, changes to a simple type also affect every field to which the 

simple type is applied as a content constraint. 

Tip! You can create a custom simple type to apply to a field as a content type 

constraint. For more information about creating a custom simple type and applying 

constraints to fields, see “Setting Constraining Facet Values” on page 243. 

� Changes to a simple type definition are saved in the IS schema. If you regenerate the 

IS schema from the XML Schema definition, your changes will be overwritten. 

� When you edit the constraining facets applied to a simple type definition, you can 

only make the constraining facet values more restrictive. The constraining facets 

cannot become less restrictive. For more information about setting values for 

constraining facets, see “Setting Constraining Facet Values” on page 243. 

Tip! If you want to edit complex type definitions, attribute declarations, element 

declarations, or the structure of the schema, you need to edit the XML Schema and then 

regenerate the IS schema. 

To edit a simple type definition 

1 Open the IS schema that contains the simple type you want to edit. 

2 In the schema browser area of the editor, select the simple type that you want to edit. 

The symbol appears next to simple types. 

3 In the schema details area, specify the constraining facets that you want to apply to 

the simple type. For more information about constraining facets, see “Constraining 

Facets” on page 464. 


Setting Constraining Facet Values 

You can edit any of the constraining facet values that appear in the schema details area 

when you select an editable simple type definition in the schema browser. The 

constraining facets displayed in the schema details area depend on the primitive type 

from which the simple type was derived. For example, if the simple type definition is 

derived from string, the schema details area displays the enumeration, length, minLength, 

maxLength, pattern, and whiteSpace facets. The schema details area only displays 

constraining facet values set in the simple type definition. It does not display constraining 



facet values the simple type definition inherited from the simple types from which it was 

derived. 

You can view the constraining facet values set in the type definitions from which a simple 

type was derived by clicking the Base Constraints button. Base constraints are the 

constraining facet values set in all the type definitions from which a simple type is 

derived—from the primitive type to the immediate parent type. These constraint values 

represent the cumulative facet values for the simple type. 

When you edit the constraining facets for a simple type definition, you can only make the 

constraining facets more restrictive—the applied constraining facets cannot become less 

restrictive. For example, if the length value is applied to the simple type, the maxLength or 

minLength values cannot be set because the maxLength and minLength facets are less 

restrictive than length. 

Creating an IS Document Type 

An IS document type contains a set of fields used to define the structure and type of data 

in a document (IData object). You can use an IS document type to specify input or output 

parameters for a service or specification. You can also use an IS document type to build a 

document or document list field and as the blueprint for pipeline validation and 

document (IData object) validation. 

IS document types can provide the following benefits: 

� Using an IS document type as the input or output signature for a service can reduce 

the effort required to build a flow. 

� Using an IS document type to build document or document list fields can reduce the 

effort needed to declare input or output parameters or the effort/time needed to build 

other document fields. 

� IS document types improve accuracy, because there is less opportunity to introduce a 

typing error typing field names. 

� IS document types make future changes easier to implement, because you can make a 

change in one place (the IS document type) rather than everywhere the IS document 

type is used. 

You can create an IS document type in the following ways: 

� Create an empty IS document type and define the structure of the document type 

yourself by inserting fields. 

� Create an IS document type from a source file, such as an XML Schema, DTD, or XML 

document. The structure and content of the IS document type will match that of the 

source file. 

� Create an IS document type from a Broker document type. 


Creating an Empty IS Document Type 


When you create an empty IS document type, you insert fields to define the contents and 

structure of the IS document type. 

Note: If you intend to make the IS document type publishable, keep in mind that the 

Broker has restrictions for field names. If you create a trigger that subscribes to the 

publishable document type, any filters that include field names containing restricted 

characters will be saved on the Integration Server only. The filters will not be saved on the 

Broker, possibly affecting Integration Server performance. For more information, see the 

Publish-Subscribe Developer’s Guide. 

To create an empty IS document type 


2 In the New dialog box, select Document Type and click Next. 

3 In the New Document Type dialog box, do the following: 

a In the list next to Folder, select the folder in which you want to save the IS 

document type. 

b In the Name field, type a name for the IS document type using any combination of 

letters, numbers, and/or the underscore character. For information about 

restricted characters, see “About Element Names” on page 45. 

c Click Next. 

4 Under Select a source, select None to indicate that you want to create an empty IS 

document type in which you define the structure and fields. 


6 To add fields in the IS document type, do the following: 

a Click on the toolbar and select the type of field that you want to define. 

b Type the name of the field and then press ENTER. 

Note: Developer prevents the insertion of fields named _env in an IS document 

type. For more information about the _env field, see “The Envelope Field” on 

page 251. 



c With the field selected, set field properties and apply constraints in the Properties 

panel (optional). 

For more information about setting field properties, see “Specifying Field 

Properties” on page 255. For information about applying constraints, see 

“Applying Constraints to Variables” on page 261. 

d If the field is a document or a document list, repeat steps a–c to define and set the 

properties and constraints for each of its members. Use to indent each 

member field beneath the document or document list field. 


Note: Developer displays small symbols next to a field icon to indicate validation 

constraints. Developer uses to indicate an optional field. Developer uses the ‡ symbol 

to denote a field with a content constraint. For information about applying constraints to 

fields, see “Applying Constraints to Variables” on page 261. 

Creating an IS Document Type from an XML Document, DTD, 

or XML Schema 

You can create an IS document type based on the structure and content of a source file, 

such as an XML Schema, DTD, or XML document. When you base the IS document type 

on a source file, Developer creates an IS document type and an IS schema. The IS 

document type has the same structure and field constraints as the source document. The 

IS schema contains the elements, attributes, and data types defined in the XML Schema or 

DTD. The IS document type, which displays the fields and structure of the source 

document, uses links to the IS schema to obtain content type information about named 

simple types. 

Keep the following points in mind when creating an IS document type from an XML 

Schema, DTD, or XML document: 

� When creating a field from an attribute declaration, the Integration Server inserts the 

@ symbol at the beginning of the field name. For example, an attribute named 

myAttribute in the source file corresponds to a field named @myAttribute in the IS 


� Before creating the IS document type and the IS schema, Integration Server validates 

the XML Schema. If the XML Schema does not conform syntactically to the schema for 

XML Schemas defined in XML Schema Part 1: Structures, Integration Server does not 

create an IS schema or an IS document type. Instead, Developer displays an error 

message that lists the number, title, location, and description of the validation errors 

within the XML Schema. 



� When you use an XML Schema to create the IS document type, the Integration Server 

uses the prefixes declared in the XML Schema as part of the field names. Field names 

have the format prefix:elementName or prefix:@attributeName. 

� If the XML Schema does not use prefixes, the Integration Server creates prefixes for 

each unique namespace and uses those prefixes in the field names. Integration Server 

uses “ns” as the prefix for the first namespace, “ns1” for the second namespace, “ns2” 

for the third namespace, and so on. 

� If you generate an IS document type from an XML Schema for which you already 

generated an IS schema, the Integration Server does not include prefixes in the field 

names. To ensure that the Integration Server uses prefixes in field names, use 

Developer to generate an IS document type from the XML Schema and allow the 

Integration Server to generate the IS schema automatically. 

� If you generate an IS document type from a DTD, the Integration Server assumes that 

the DTD is UTF8-encoded. If the DTD is not UTF8-encoded, add the XML prolog to 

the top of the DTD and explicitly state the encoding. For example, for a DTD encoded 

in 8859-1, you would insert the following at the top of the document: 

 

To create an IS document type from an XML document, DTD, or XML Schema 







letters, numbers, and/or the underscore character. For information about reserved 

words or characters, see “About Element Names” on page 45. 

c Click Next. 

4 Under Select a source, select one of the following: 


XML Create an IS document type that matches the structure and fields in 

an XML document. 

DTD Create an IS document type that matches the structure and fields in 

a DTD. 



5 Click Next. 


XML Schema Create an IS document type that matches the structure and fields in 

an XML Schema definition. 

6 In the Enter the URL or select a local file box, do one of the following: 

� If you want to base the IS document type on a file that resides on the Internet, type 

the URL of the resource. (The URL you specify must begin with http: or 

https:.) 

� If you want to base the IS document type on a file that resides on your local file 

system, type in the path and file name, or click to navigate to and select the 

file. 


� If you selected XML in step 4, click Finish. Developer generates the IS document 

type using the XML document you specified and displays it in the editor. 

� If you selected DTD or XML Schema in step 4, click Next. Developer prompts you to 

select the root element of the document. Select the root element and click OK. 

Developer generates the IS document type and displays it in the editor. Developer 

also generates an IS schema and displays it in the Navigation panel. 

Developer creates the IS document type and saves it on the Integration Server. If you 

want to add or edit fields in the IS document type, see “Creating an Empty IS 

Document Type” on page 245. 

Note: You might receive errors or warnings when creating an IS document type from a 

DTD or XML Schema definition. For more information about these errors and 

warnings, see “Validation Errors” on page 468. 

Tip! You can modify the generated IS document type by adding, moving, or deleting fields 

or by applying properties to the fields. For more information about applying properties to 

fields, see “Specifying Field Properties” on page 255 

Creating an IS Document Type from a Broker Document Type 

If your Integration Server is connected to a Broker, you can create an IS document type 

from a Broker document type. The IS document type retains the structure, fields, data 

types, and publication properties defined in the Broker document type. For detailed 

information about how a Broker document type translates to an IS document type and 

vice versa, see the Publish-Subscribe Developer’s Guide. 



When you create an IS document type from a Broker document type, you essentially 

create a publishable document type. A publishable document type is an IS document type 

with specific publishing properties, such as storage type and time to live. Additionally, a 

publishable document type on an Integration Server is bound to a Broker document type. 

An instance of a publishable document type can be published to a Broker or locally within 

an Integration Server. 

A publishable document type can be used anywhere an IS document type can be used. 

For example, you can use a publishable document type to define the input or output 

parameters of a service. A document reference field can reference an IS document type or 

a publishable document type. You can use a publishable document type as the blueprint 

for performing document or pipeline validation. 

Tip! Any IS document type can be made into a publishable document type. For 

information about making a document type publishable or setting publication properties, 

see the Publish-Subscribe Developer’s Guide. 

When you create an IS document type from a Broker document type that references other 

elements, Developer will also create an element for each referenced element. The 

Integration Server will contain a document type that corresponds to the Broker document 

type and one new element for each element the Broker document type references. 

Developer also creates the folder in which the referenced element was located. Developer 

saves the new elements in the package you selected for storing the new publishable 


For example, suppose that the Broker document type references a document type named 

address in the customerInfo folder. Developer would create an IS document type named 

address and save it in the customerInfo folder. If a field in the Broker document type was 

constrained by a simple type definition declared in the IS schema purchaseOrder, Developer 

would create the referenced IS schema purchaseOrder. 

An element referenced by a Broker document type might have the same name as an 

existing element on your Integration Server. However, element names must be unique on 

the Integration Server. Developer gives you the option of overwriting the existing 

elements with the referenced elements. 

Important! If you do not select the Overwrite existing elements when importing referenced 

elements check box and the Broker document type references an element with the same 

name as an existing Integration Server element, Developer will not create the publishable 




Important! If you choose to overwrite existing elements with new elements, keep in mind 

that dependents of the overwritten elements will be affected. For example, suppose the 

address document type defined the input signature of a flow service deliverOrder. 

Overwriting the address document type might break the deliverOrder flow service and any 

other services that invoked deliverOrder. 

To create an IS document type from a Broker document type 







letters, numbers, and/or the underscore character. 

c Click Next. 

4 Under Select a source, select Broker Document Type, and click Next. 


a In the Broker Namespace field, select the Broker document type from which you 

want to create an IS document type. The Broker Namespace field lists all of the 

Broker document types on the Broker territory to which the Integration Server is 

connected. 

b If you want to replace existing elements in the Navigation panel with identically 

named elements referenced by the Broker document type, select the Overwrite 

existing elements when importing referenced elements check box. 

Important! Overwriting the existing elements completely replaces the existing 

element with the content of the referenced element. Any elements on the 

Integration Server that depend on the replaced element, such as flow services, IS 

document types, and specifications, might be affected. 

6 Click Finish. Developer automatically refreshes the Navigation panel and displays 

beside the document type name to indicate it is a publishable document type. 


Notes: 


� You can associate only one IS document type with a given Broker document type. 

If you try to create a publishable document type from a Broker document type 

that is already associated with a publishable document type on your Integration 

Server, Developer displays an error message. 

� In the Publication category of the Properties panel, the Broker doc type property 

displays the name of the Broker document type used to create the publishable 

document type. Or, if you are not connected to a Broker, this field displays Not 

Publishable. You cannot edit the contents of this field. For more information about 

the contents of this field, see the Publish-Subscribe Developer’s Guide. 

� Once a publishable document type has an associated Broker document type, you 

need to make sure that the document types remain in sync. That is, changes in one 

document type must be made to the associated document type. You can update 

one document type with changes in the other by synchronizing them. For 

information about synchronizing document types, see the Publish-Subscribe 


The Envelope Field 

All publishable document types contain an envelope (_env) field. This field is a document 

reference to the pub:publish:envelope document type. This document type defines the content 

and structure of the envelope that accompanies instances of the publishable document. 

The envelope records information such as the sender’s address, the time the document 

was sent, sequence numbers, and other useful information for routing and control. The 

envelope is much like a header in an e-mail message. 

Because the _env field is needed for publication, Developer controls the usage of the _env 

field in the following ways: 

� You cannot insert an _env field in a document type. Developer automatically inserts 

the _env field at the end of the document type when you make the document type 

publishable. 

� You cannot copy and paste the _env field from one document type to another. You can 

copy this field to the Input/Output tab. 

� You cannot move, rename, or cut the _env field from a document type. Developer 

automatically removes the _env field when you make a document type unpublishable. 

� You can only delete an _env field from a document type that is not publishable. 

� The _env field is always the last field in a publishable document type. 

For more information about the _env field and the contents of the pub:publish:envelope 

document type, see the Publish-Subscribe Developer’s Guide. 



Note: If an IS document type contains a field named _env, you need to delete that field 

before you can make the IS document type publishable. 

Adapter Notifications and Publishable Document Types 

Adapter notifications notify webMethods components whenever a specific event occurs on 

an adapter's resource. The adapter notification publishes a document when the specified 

event occurs on the resource. For example, if you are using the JDBC Adapter and a 

change occurs in a database table that an adapter notification is monitoring, the adapter 

notification publishes a document containing data from the event and sends it to the 


An adapter notification can have an associated publishable document type . When you 

create a polling or asynchronous listener adapter notification in Developer, the 

Integration Server automatically generates a corresponding publishable document type. 

Developer assigns the publishable document type the same name as the adapter 

notification, but appends PublishDocument to the name. That is, Developer assigns the 

publishable document type the name: NotificationNamePublishDocument. You can use this 

publishable document type with triggers and flow services just as you would any other 

publishable document type. 

In a publishable document type associated with an adapter notification, you can edit only 

the Storage type and Time to live publication properties. To make any other modifications to 

the publishable document type, you must modify the adapter notification type. 

Integration Server automatically applies the changes to the publishable document type. 

For information about publication properties, see the Publish-Subscribe Developer’s Guide. 

For more information about creating and using adapter notifications, see the appropriate 

adapter user guide. For more information about performing actions on adapter 

notifications and their associated publishable document types, see Chapter 2, “Managing 

Elements in the Navigation Panel”. 

Editing an IS Document Type 

When you make a change to an IS document type, keep in mind that any change is 

automatically propagated to all services, specifications, document fields, and document 

list fields that use or reference the IS document type. (This happens when you save the 

updated IS document type to the server.) You can use the Tools�Find Dependents command 

to view a list of elements that use the IS document type and will be affected by any 

changes. 

Important! If you use an IS document type as the blueprint for pipeline or document 

validation, any changes you make to the IS document type can affect whether the object 

being validated (pipeline or document) is considered valid. For more information about 

validation, see Chapter 10, “Performing Data Validation”. 


Modifying Publishable Document Types 


When you modify a publishable document type, such as by deleting a field or changing a 

property, the publishable document type is no longer synchronized with the 

corresponding document type on the Broker. When you save your changes to the 

publishable document type, Developer displays a message stating: 

This document type is now out of sync with the associated Broker 

document type. Use Sync Document Type to synchronize the document type 

with the Broker. 

Developer displays this message only if a Broker is configured for the Integration Server. 

To update the associated Broker document type with the changes, synchronize the 

publishable document type with the Broker document type. For more information about 

synchronizing document types, see the Publish-Subscribe Developer’s Guide. 

Printing an IS Document Type 

You can use the View as HTML command to produce a printable version of an IS document 

type. 

To print an IS document type 

1 Open the IS document type you want to print and click its title bar in the editor to give 

it the focus. 

2 From the File menu, select View as HTML. 

Developer expands any document and document list fields in the IS document type, 

creates an HTML page containing the IS document type, and displays the HTML page 

in your default browser. 

3 If you want to print the IS document type, select your browser’s print command. 

Using an IS Document Type to Specify Service Input or 

Output Parameters 

You can use an IS document type as the set of input or output parameters for a service or 

specification. If you have multiple services with identical input parameters but different 

output parameters, you can use an IS document type to define the input parameters rather 

than manually specifying individual input fields for each service. 

To use an IS document type as service input or output parameters 

1 Open the service to which you want to assign the IS document type. 

2 Click the Input/Output tab. 



3 In the Input or Output box (depending on which half of the Input/Output tab you want to 

apply the IS document type to), type the fully qualified name of the IS document type 

or click to select it from a list. You can also drag an IS document type from the 

Navigation panel to the box below the Validate input or Validate output check boxes on 

the Input/Output tab. 


Important! When an IS document type is assigned to the input or output of a service, 

you cannot add, delete, or modify the fields on that half of the Input/Output tab. 

Using an IS Document Type to Build a Document Reference 

or Document Reference List Field 

You can use an IS document type to build a document reference or document reference list 

field. By referencing an IS document type instead of creating a new one, you can reduce 

the time required to create fields and maintain better consistency for field names. You 

might find referencing fields especially useful for information that is repeated over and 

over again, such as address information. 

Tip! You can also use a publishable document type to build a document reference or 

document reference list field. 

To use a document type to build a document reference or document reference list 

1 On the Input/Output tab, click on the toolbar and select one of the following: 

Click... To... 

Document Reference Create a document field based on an IS document type. 

Document Reference 

List 

Create a document list field based on an IS document type. 

2 In the Name field, type the fully qualified name of the IS document type or select it 

from the list next to Folder. 

3 Click OK. 

4 Type the name of the field. 

5 Press ENTER. 



Important! If you are creating a document reference or document reference list field 

based on an IS document type, you cannot directly add, delete, or modify its members 

on the Input/Output tab. To edit the referenced document or document list, select it in 

the Navigation panel, lock it, and then edit its fields in the editor. 

Tip! You can also add a document reference by dragging an IS document type from the 

Navigation panel to the box below the Validate input or Validate output check boxes on the 

Input/Output tab. 

Specifying Field Properties 

You can specify additional properties for the field. These properties are located in the 

Properties panel. 

Field properties 

On the Properties panel, the General category contains the properties of the field and the 

Constraints category contains validation constraints for the field. (For more information 

about specifying validation constraints, see “Applying Constraints to Variables” on 

page 261.) 

Note: Use the XML Namespace property to assign a namespace name to a field. The 

namespace name indicates the namespace to which the field belongs. When generating 

XML Schema definitions and WSDL documents, the Integration Server uses the value of 

the XML Namespace field along with the field name (the local name) to create a qualified 

name (QName) for the field. For more information about setting the XML Namespace 

property, see the Web Services Developer’s Guide. 

The Text Field, Password, Large Editor, and Pick List options of the String display type property 

affect how you input data for the field as follows. These options are not available for 

Objects and Object lists. 


Creating a Specification 


If you want the input… Select... 

Entered in a text field Text Field (default) 

Entered as a password, with asterisks reflected instead of 

characters 

Password 

Entered in a large text area instead of a text field. This is useful if 

you expect a large amount of text as input for the field, or you need 

to have TAB or new line characters in the input 

To be limited to a predefined list of values 

Use the Pick list choices property’s Edit button to define the values 

that will appear as choices when Developer prompts for input at 

run time. 

A specification is a “free-standing” IS element that defines a set of service inputs and 

outputs. If you have multiple services with the same input and output requirements, you 

can point each service to a single specification rather than manually specify individual 

input and output fields in each service. 

Using specifications provides the following benefits: 

� It reduces the effort required to build each flow. 

� It improves accuracy, because there is less opportunity to introduce a typing error 

when defining a field name. 

� It makes future specification changes easier to implement, because you can make the 

change in one place (the specification) rather than in each individual service. 

If you use a specification, keep in mind that: 

Large Editor 

Pick List 

� Any change that you make to the specification is automatically propagated to all 

services that reference that specification. (This happens the moment you save the 

updated specification to the server.) 

� A specification wholly defines the input and output parameters for a service that 

references it. This means that you cannot directly alter the service’s input and output 

parameters through its Input/Output tab. (Developer displays the parameters, but does 

not allow you to change them.) To make changes to the input and output parameters 

of the service, you must modify the specification (which affects all services that 

reference it) or detach the specification so you can manually define the parameters on 

the service’s Input/Output tab. 

You create a specification with Developer. You assign a specification to a service using the 

Input/Output tab for the service. 


To create a specification 


2 In the New dialog box, select Specification, and click Next. 


3 In the New Service Specification dialog box, do the following: 

a In the list next to Folder, select the folder to which you want to save the 

specification. 

b In the Name field, type a name for the specification using any combination of 

letters, numbers, and the underscore character. 

Important! Developer does not allow the use of certain reserved words (such as for, 

while, and if ) as names. If you specify a name that is a reserved word, you will receive 

an error message. When this happens, use a different name or try adding a letter or 

number to the name you specified to make it valid. 

c Click Finish. 

4 If you want this specification to reference another specification, do the following in 

the editor: 

a In Specification Reference field, type the specification’s name or click to select it 

from a list. 

b Skip the rest of this procedure. 

Important! Typically, you do not build a specification by referencing another 

specification. However, it is useful to do this in the situation where you will use the 

specification with a group of services whose requirements are expected to change 

(that is, they match an existing specification now but are expected to change at some 

point in the future). Referencing a specification gives you the convenience of using an 

existing specification and the flexibility to change the specification for only that single 

group of services in the future. 

5 If you want to reference an IS document type for the Input or Output half of the 

specification, do the following: 

a In the Input or Output field (depending on which half of the specification you want 

to assign the IS document type to), type the IS document type name or click to 

select it from a list. You can also drag an IS document type from the Navigation 

panel to the box below the Validate input or Validate output check boxes on the 



Input/Output tab. For information about creating IS document types, see “Creating 

an IS Document Type” on page 244. 

Tip! You can select a publishable document type or an IS document type to define 

the input or output half of the specification. 

b Proceed to the next step to specify the fields for the other half of the specification. 

(If you assigned IS document types to both the Input and Output sides of this 

specification, skip the rest of this procedure.) 

Important! Once you assign an IS document type to the Input or Output side of a 

specification, you cannot add, delete, or modify the fields on that half of the 


6 For each input or output field that you want to define, do the following: 

a Select the half of the specification (Input or Output) where you want to define the 

field by clicking anywhere in that half’s large white text box. 

b Click on the toolbar and select the type of field that you want to specify. 

c Type the name of the field and then press ENTER. 

d With the field selected, set its properties and apply constraints on the Properties 

panel (optional). 

For details on setting field properties, see “Specifying Field Properties” on 

page 255. For details on applying constraints, see “Applying Constraints to 


e If the field is a document or a document list, repeat steps b–d to define each of its 

members. Use to indent each member beneath the document or document list 

field. 


To assign a specification to a service 

1 Open the service to which you want to assign a specification. 


3 In Specification Reference, type the fully qualified name of the specification, or click 

to select it from a list. 

Important! When a specification is assigned to a service, you cannot add, delete, or modify 

the declared fields using that service’s Input/Output tab. 


Chapter 10. Performing Data Validation 

� What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

� Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

� Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 

� Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 

� Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 

� Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 271 

� Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

� Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 


What Is Data Validation? 

10. Performing Data Validation 

Data validation is the process of verifying that run-time data conforms to a predefined 

structure and format. Data validation also verifies that run-time data is a specific data 

type and falls within a defined range of values. 

By performing data validation, you can make sure that: 

� The pipeline, a document (IData object), or an XML document contains the data 

needed to execute subsequent services. For example, if a service processes a purchase 

order, you might want to verify that the purchase order contains a customer name and 

address. 

� The data is in the structure expected by subsequent services. For example, a service 

that processes a purchase order might expect the customer address to be a document 

field with the following fields: name, address, city, state, and zip. 

� Data is of the type and within a value range expected by a service. For example, if a 

service processes a purchase order, you might want to make sure that the purchase 

order does not contain a negative quantity of an item (such as -5 shirts). 

By using the data validation capabilities built into webMethods Integration Server, you 

can decide whether or not to execute a service based on the validity of data. The validation 

capabilities can also eliminate extra validation code from your services. 

What Is Data Validated Against? 

During validation, run-time data is compared to a blueprint or model. The blueprint or 

model is a formal description of the structure and the allowable content for the data. The 

blueprint identifies structural and content constraints for the data being validated. The 

validation engine in webMethods Integration Server considers the data to be valid when it 

conforms to the constraints specified in the blueprint. A blueprint can be an IS schema, an 

IS document type, or a set of input and output parameters. 

The blueprint used to validate data depends on the type of validation you are performing. 

In webMethods Integration Server, you can perform the following types of validation: 

� Input/Output validation. The validation engine in webMethods Integration Server 

validates the input and/or output of a service against the signature of the service. 

� Document validation. The validation engine in webMethods Integration Server validates 

the structure and content of a document (IData object) in the pipeline against an IS 


� Pipeline validation. The validation engine in webMethods Integration Server validates 

the structure and content of the pipeline against an IS document type. 

� XML validation. The validation engine in webMethods Integration Server validates the 

structure and content of an XML document against an IS schema. 



The following sections provide information about performing each type of validation and 

information about applying constraints to fields. 

Applying Constraints to Variables 

In pipeline, document, and input/output validation, the blueprint used for data validation 

requires constraints to be applied to its variables. Constraints are the restrictions on the 

structure or content of variables. You can apply the following types of constraints to 

variables: 

� Structural constraints specify the existence and structure of variables at run time. For 

example, if the flow service in which you are validating the pipeline processes a 

purchase order, you might want to check that values for the purchaseOrderNumber, 

accountNumber, and customerName variables exist at run time. 

For document and document list variables, you can also specify the structure of the 

variable; that is, you can specify what variables can be contained in the document 

(IData object) or document list (IData[ ] object) at run time. For example, you could 

specify that the lineItem document variable must contain the child variables 

itemNumber, quantity, size, color, and unitPrice. You could also specify that the lineItem 

document can optionally contain the child variable specialInstructions. 

� Content constraints describe the data type for a variable and the possible values for the 

variable at run time. You can apply content constraints to String, String list, String 

table, Object, and Object list variables. 

When you specify a content constraint for a String, String list or String table variable, 

you can also apply a constraining facet to the content. A constraining facet places 

limitations on the content (data type). For example, for a String variable named 

itemQuantity, you might apply a content constraint that requires the value to be an 

integer. You could then apply constraining facets that limit the content of itemQuantity 

to a value between 1 and 100. 

You can use simple types from an IS schema as content constraints for String, String 

list, or String table variables. 

For pipeline and document validation, the IS document type used as the blueprint needs 

to have constraints applied to its variables. For input/output validation, constraints need 

to be applied to the declared input and output parameters of the service being validated. 

Note: When you create an IS document type from an XML Schema or a DTD, the 

constraints applied to the elements and attributes in the original document are preserved 

in the new IS document type. For more information about creating IS document types, see 

“Creating an IS Document Type” on page 244. 


To apply constraints to a variable 

1 Select the variable to which you want to apply constraints. 


You can apply constraints to variables in IS document types, variables in a 

specification, and variables declared on the Input/Output tab. 

2 In the Constraints category on the Properties panel, do the following: 

a If you want to require the selected variable to exist at run time, set the Required 

property to True. If the existence of the variable is optional, set this property to 

False. 

b If you want to allow a variable to have a null value, set the Allow null property to 

True. If you want the validation engine to generate an error when the variable has 

a null value, set the Allow null property to False. 

c If the selected variable is a document or document list and you want to allow it to 

contain undeclared child variables, set the Allow unspecified fields property to True. 

If this property is set to False, any child variables that exist in the pipeline but do 

not appear in the declared document field will be treated as errors at run time. 

Note: The state of the Allow unspecified fields property determines whether the 

document is open or closed. An open document permits undeclared fields 

(variables) to exist at run time. A closed document does not allow undeclared 

fields to exist at run time. The Integration Server considers a document to be open 

if the Allow unspecified fields property is set to True and considers a document to be 

closed if the Allow unspecified fields property is set to False. 

d If the selected variable is a String, String list, or String table, and you want to 

specify content constraints for the variable, click and then do one of the 

following: 

� If you want to use a content type that corresponds to a built-in simple type in 

XML Schema, in the Content type list, select the type for the variable contents. 

(For a description of these content constraints, see Appendix F, “Validation 

Content Constraints”.) To apply the selected type to the variable, click OK. 

If you want to customize the content type by changing the constraining facets 

applied to the type, see “Customizing a String Content Type” on page 264. 

� If you want to use a simple type from an IS schema as the content constraint, 

click the Browse button. In the Browse dialog box, select the IS schema 

containing the simple type you want to apply. Then, select the simple type 

you want to apply to the variable. To apply the selected type to the variable, 

click OK. 



If you want to customize the content type by changing the constraining facets 

applied to the type, see “Customizing a String Content Type” on page 264. 

Note: A content type corresponds to a simple type from an XML Schema 

definition. All of the choices in the Content type list correspond to simple types 

defined in XML Schema Part 2: Datatypes. 

e If the selected variable is an Object or Object list, for the Java wrapper type property, 

select the Java class for the variable contents. If you do not want to apply a Java 

class or if the Java class is not listed, select UNKNOWN. 

For more information about supported Java classes for Objects and Object lists, 

see “Java Classes for Objects” on page 421. 

3 Repeat this procedure for each variable to which you want to apply constraints in the 

IS document type, specification, service input, or service output. 


Considerations for Object Constraints 

Constraints for Object and Object list variables correspond to Java classes, whereas 

constraints for String variables correspond to simple types in XML schemas. When you 

apply constraints to Objects and perform validation, the data is validated as being of the 

specified Java class. For details on the Java classes you can apply to an Object or Object 

list, see “Java Classes for Objects” on page 421. 

A constrained Object is validated when one of the following occur: 

� A service runs with the Validate input or Validate output check box selected on the 


� A service runs via the INVOKE step in a flow service with the Validate input or Validate 

output properties set on the INVOKE step. 

� The pub.schema:validate service runs. 

� A document is published. When this occurs, the contents of the document are 

validated against the specified document type. For details, see the Publish-Subscribe 


� During testing, when you enter values for a constrained Object or Object list in the 

Input dialog box. 

� When you assign a value to an Object or Object list variable on the Pipeline tab using 

the Set Value modifier. 


Customizing a String Content Type 


Instead of applying an existing content type or simple type to a String, String list, or String 

table variable, you can customize an existing type and apply the new, modified type to a 

variable. You customize a content type or simple type by changing the constraining facets 

applied to the type. 

When you customize a type, you actually create a new content type. Developer saves the 

changes as a new content type named contentType_customized. For example, if you 

customize the string content type, Developer saves the new content type as 

string_customized. 

Note: When you edit a simple type definition in an IS schema, the changes are saved to the 

selected type definition in the IS schema. The modifications affect any variable to which 

the simple type is applied as a content type constraint. For more information about 

editing a simple type definition, see “Editing a Simple Type in an IS Schema” on page 242. 

When customizing a content type, keep the following points in mind: 

� When you edit the constraining facets applied to a content type, you can only make 

the constraining facet values more restrictive. The constraining facets cannot become 

less restrictive. For more information about setting values for constraining facets, see 

“Setting Constraining Facet Values” on page 243. 

� The constraining facets you can specify depend on the content type. For more 

information about the constraining facets for each content type, see Appendix C, 

“Supported Data Types” on page 419. 

� The customized content type applies only to the selected variable. To make changes 

that affect all variables to which the content type is applied, edit the content type in 

the IS schema. (String content types are simple types from IS schemas.) For more 

information about editing simple types, see “Editing a Simple Type in an IS Schema” 

on page 242. 

To customize a content type 

1 Select the variable to which you want to apply a customized content type. 

2 In the Constraints category on the Properties panel, click the Content type browse button 

( ) and then do one of the following to select the content type you want to 

customize: 

� In the Content type list, select the content type you want to customize. 

� If you want to customize a simple type from an IS schema, click the Browse button. 

In the Browse dialog box, select the IS schema containing the simple type. Then, 

select the simple type you want to customize and apply to the variable. 



3 Click the Customize button. Developer makes the constraining facet fields below the 

Content type list available for data entry (that is, changes the background of the 

constraining facet fields from grey to white). Developer changes the name of the 

content type to contentType_customized. 

4 In the fields below the Content type list, specify the constraining facet values you want 

to apply to the content type. For more information about constraining facets, see 

“Constraining Facets” on page 464. 

5 Click OK. Developer saves the changes as a new content type named 

contentType_customized. 

Note: The constraining facets displayed below the Content type list depend on the 

primitive type from which the simple type is derived. Primitive types are the basic data 

types from which all other data types are derived. For example, if the primitive type is 

string, Developer displays the constraining facets enumeration, length, minLength, 

maxLength, and pattern. For more information about primitive types, refer to XML 

Schema Part 2: Datatypes at http://www.w3.org/TR/xmlschema-2/. 

Important! Developer throws exceptions at design time if the constraining facet values 

for a content type are not valid. For more information about these exceptions, see 

Appendix G, “Validation Errors and Exceptions” 

Viewing the Constraints Applied to Variables 

Developer displays small symbols next to a variable icon to indicate the constraints 

applied to the variable. Developer displays variables in the following ways: 

Variable Constraint status 

Required field. 

Optional field. 

Required field with content type constraint 

Optional field with content type constraint 



Note: Developer displays the ‡ symbol next to String, String list, and String table variables 

with a content type constraint only. Developer does not display the ‡ symbol next to 

Object and Object list variables with a specified Java class constraint. Object and Object 

lists with an applied Java class constraint have a unique icon. For more information about 

icons for constrained Objects, see “Java Classes for Objects” on page 421. 

Performing Input/Output Validation 

In input/output validation, the validation engine in webMethods Integration Server 

validates the inputs and/or outputs of a service against the declared input and output 

parameters of the service. If you specify that you want to validate the inputs to the service, 

the validation engine validates the service input values immediately before the service 

executes. If you specify that you want to validate the outputs of the service, the validation 

engine validates the service output values immediately after the service executes. An 

input or output value is invalid if it does not conform to the constraints applied to the 

input or output parameter. 

For input/output validation, the services’s declared input and output parameters act as the 

blueprint or model against which input/output values are validated. To effectively use the 

input and output parameters as the blueprint for validation, you need to apply constraints 

to the parameters. For information about applying constraints to variables, see “Applying 

Constraints to Variables” on page 261. For information about declaring service input and 

output parameters, see “Declaring Input and Output Parameters for a Service” on 

page 129. 

. 

Note: The declared input and output parameters for a service are sometimes called the 

signature of the service. 

You can specify that you want to perform input/output validation for a service in the 

following ways: 

� Input/Output tab. Set properties on the Input/Output tab to instruct the validation engine 

in webMethods Integration Server to validate the inputs and/or outputs of the service 

every time the service executes. If a client calls the service and the inputs are invalid, 

the service fails and does not execute. 

� INVOKE step properties. Set up input/output validation via the INVOKE step properties 

to instruct the validation engine to validate the service input and/or output only when 

it is called from within another flow service. At run time, if the inputs and/or outputs 

of the service are invalid, the INVOKE flow step that calls the service fails. 

To determine which method to use, determine whether or not you want the service input 

and output values validated every time the service runs. If you want to validate the input 

and output values every time the service runs, specify validation via the Input/Output tab. 



For example, if your service requires certain input to exist or fall within a specified range 

of values, you might want the pipeline validated every time the service runs. 

If the input and/or output values do not need to be validated every time the service 

executes, set up validation via the INVOKE step properties. Specifying input/output 

validation via the INVOKE step properties allows you to decide on a case-by-case basis 

whether you want validation performed. 

Note: If you specify input/output validation via the INVOKE step and an input or output 

value is invalid, the service itself does not actually fail. The validation engine validates 

input values before webMethods Integration Server executes the service. If the service 

input is not valid, the INVOKE flow step for the service fails. Similarly, the validation 

engine validates output values after webMethods Integration Server executes the service. 

If the service output is not valid, the INVOKE flow step for the service fails. Whether or 

not the entire flow service fails when an individual flow step fails depends on the exit 

conditions for the service. For information about specifying exit conditions, see “Using 

SEQUENCE to Specify an Exit Condition” on page 185. 

Specifying Input/Output Validation via the Input/Output Tab 

You can specify that you want the inputs and/or outputs of a service validated every time it 

executes by setting properties on the Input/Output tab of the service. Every time the service 

executes, the validation engine validates the input and/or output values of the service 

against the input and output parameters declared for the service. 

To set up input and output validation via the Input/Output tab 

1 Open the service for which you want to validate input and/or output every time the 

service is invoked. 


3 If you want the input of the service validated every time the service executes, select 

the Validate input check box. 

4 If you want the output of the service validated every time the service executes, select 

the Validate output check box. 



Service input values will 

be validated every time 

the service executes. 

Input/Output tab with validation processing enabled 


Specifying Input/Output Validation via the INVOKE Step 

You can also specify input/output validation by setting properties for the INVOKE step 

that calls the service. Each time you insert a service into a flow, you can decide whether 

you want the validation engine to validate service inputs and/or outputs at run time. 

To set up input and output validation via the INVOKE step 

1 In the flow editor, select the INVOKE step containing the service for which you want 

Integration Server to validate input and/or output values. 

2 In the General category on the Properties panel, do the following: 

� If you want to validate input to the service, set the Validate input property to True. 

� If you want to validate the output of the service, set the Validate output property to 

True. 


Service output 

values will not be 

validated. 


INVOKE properties with validation processing enabled 

Performing Document Validation 


Inputs to the invoked 

service will be 

validated. 

Outputs of the 

service will not be 

validated. 

Important! Keep in mind that the Validate input and Validate output properties are independent 

of any validation settings that you might have already set in the service. If you select the 

Validate input and/or Validate output check boxes on the Input/Output tab of the invoked 

service, then every time the service executes, input/output validation is performed. If you 

also specify input/output validation via the INVOKE step, duplicate validation will result, 

possibly slowing down the execution of the service. 

Sometimes, you might want to validate an individual document (IData object) in the 

pipeline instead of the entire pipeline. Using the pub.schema:validate service, you can 

validate a single document (IData object) in the pipeline against an IS document type. 

For example, suppose that you invoke the pub.ldap:lookup service in a flow to retrieve an 

IData object from an LDAP directory service. If you want to validate that object before you 

use it in other services, invoke the pub.schema:validate service after retrieving the object. As 

another example, you might want to validate an XML document that has been converted 

to document (IData object). You would use the pub.schema:validate service to validate the 

resulting document (IData object) against an IS document type. 

The pub.schema:validate service considers a document (IData object) to be valid when it 

complies with the structural and content constraints described in the IS document type it 



is validated against. This service returns a string that indicates whether validation was 

successful and an IData array that contains any validation errors. When you insert the 

pub.schema:validate service into a flow service, you can specify the maximum number of 

errors to be collected by the service. You can also specify whether the pub.schema:validate 

service should fail if the document (IData object) is invalid. 

For more information about the pub.schema:validate service, see the webMethods Integration 

Server Built-In Services Reference. 

Note: The validation engine in Integration Server performs document (IData object) 

validation automatically when a document is published. The validation engine validates 

the published document against the publishable document type. 

Tip! If you want to validate only String, String list, or String table variables in the pipeline, 

use the pub.schema:validatePipeline service. Define an IS document type that contains the 

variables you want to validate and apply constraints to the variables. Then use this IS 

document type as the blueprint for the pub.schema:validatePipeline service. Only the variables 

in the IS document type will be validated. The validation engine ignores other variables 

that exist in the pipeline at run time. (An IS document type implicitly allows unspecified 

variables to exist at run time.) 

Performing Pipeline Validation 

Pipeline validation is the process of verifying the contents of the pipeline against an IS 

document type. By validating pipeline data, you can: 

� Ensure a higher degree of accuracy for pipeline content. 

� Execute or not execute a service based on the validity of the pipeline data. 

� Eliminate extra validation code in your service. 

In pipeline validation, an IS document type is the blueprint or model against which you 

validate the pipeline. The constraints applied to the variables in the IS document type 

determine what can and cannot be included in the pipeline. For more information about 

applying constraints to variables, see “Applying Constraints to Variables” on page 261. 

To validate the pipeline, invoke the built-in service pub.schema:validatePipeline. This service 

instructs the validation engine to compare the pipeline contents against a specified IS 

document type. The pipeline is valid when it conforms to the structural and content 

constraints applied to the IS document type. The pub.schema:validatePipeline service returns a 

string that indicates whether validation was successful and an IData array (errors variable) 

that contains any validation errors. For more information about the 

pub.schema:validatePipeline service, see the webMethods Integration Server Built-In Services 

Reference. 



Performing XML Validation in webMethods Integration Server 

In webMethods Integration Server, XML validation is the process of verifying the 

structure and content of an XML document against an IS schema. By validating an XML 

document, you can ensure that the XML document contains the elements and attributes 

organized in the structure or format expected by subsequent services. You can also ensure 

that the elements and attributes contain values that are of the data type expected by 

subsequent services. In webMethods Integration Server, an XML document is valid when 

it complies with the structural and content constraints described in the IS schema it is 

validated against. 

For example, if you receive an XML document that contains new employee information, 

you might want to validate the employee information before executing subsequent 

services. You might want to make certain the XML document contains an employee name, 

an address, telephone number, and date of birth information. Additionally, you might 

want to validate the date of birth information to make sure that it conforms to a specific 

date format. 

To validate an XML document, invoke the pub.schema:validate service. This service instructs 

the validation engine to validate an XML document by comparing it to a specified IS 

schema or an IS document type in the Navigation panel. The XML document is valid if it 

complies with the structural and content constraints described in the IS schema or IS 

document type. The pub.schema:validate service returns a string that indicates whether 

validation was successful and an errors variable (an IData array) that contains any 

validation errors. 

Important! The pub.schema:validate service requires a parsed XML document as input (an 

XML node). The Integration Server parses XML documents it receives via HTTP or FTP 

automatically. You can also use the pub.xml:loadXMLNode service or the 

pub.xml:xmlStringToXMLNode to parse an XML document. For more information about 

submitting XML documents to services, see the XML Services Developer’s Guide. For more 

information about the pub.xml services, see the webMethods Integration Server Built-In 


Note: For information about errors that can occur during validation, see “Validation Errors 

and Exceptions” on page 273. 

Performing Validation from within a Java Service 

You can use built-in services pub.schema:validate and pub.schema:validatePipeline to perform 

validation from within a Java service. In the following example, the pub.schema:validate 

service is used to validate the results of the pub.xml:xmlNodeToDocument service against a 

specification for an OAG purchase order. 


. 

. 

. 

IData validInput; 

IData dtrResult; 

. 

. 

. 


// initialize the folder and document type name to point to a document type 

// that exists on webMethods Integration Server 

String ifc = "OAG.PO" 

String rec = "purchaseOrder" 

// put the result from the xmlNodeToDocument service (i.e, the object to be 

// validated) into the key named 

IDataCursor validCursor = validInput.getCursor(); 

IDataCursor dtrCursor = drtResult.getCursor(); 

if (dtrCursor.first("boundNode")) { 

// assumption here that there's data at the current cursor position 

validCursor.insertAfter( "object", dtrCursor.getValue() ); 

} 

dtrCursor.destroy(); 

// set the parameter to point to the document type to validate 

// against 

// This document type must exist on webMethods Integration Server 

validCursor.insertAfter( "conformsTo", ifc+":"+rec ); 

// set the parameter to the number of allowed validation errors 

validCursor.insertAfter( "maxErrors", "1000" ); 

validCursor.destroy(); 

// invoke pub.schema.validate to validate contents of 

IData validResult = context.invoke("pub.schema", "validate", validInput); 

// check to see whether is valid and process accordingly 

IDataCursor validCursor = validResult.getCursor(); 

if(validCursor.first("isValid")) 

{ 

if (IDataUtil.getString(validCursor).equals("false")) 

{ 

IData [] vr = IDataUtil.getIDataArray(validCursor, "errors"); 

System.out.println ( vr.length+" ERROR(s) found with example"); 

for (int j=0; j < vr.length; j++ ) 

{ 

System.out.println( vr[j].toString() ); 

} 

} 

} 

validCursor.destroy(); 

. 

. 

. 



For additional information about pub.schema:validate and pub.schema:validatePipeline, see the 

Schema services in the webMethods Integration Server Built-In Services Reference. 

Validation Errors and Exceptions 

During data validation, the validation engine generates errors when it encounters values 

that do not conform to the structural and content constraints specified in the blueprint. 

The format in which the validation engine returns errors depends on whether validation 

was performed using the built-in services or by checking the declared input and output 

parameters for the service. 

� When the validation engine performs data validation by executing the built-in 

services pub.schema:validate or pub.schema:validatePipeline, errors are returned in the errors 

output variable (an IData list). For each validation error, the errors variable lists the 

error code, the error message, and the location of the error. 

� When the validation engine performs validation by comparing run-time data to the 

declared input and output parameters, the validation engine returns all the validation 

errors in a string. This string contains the error code, error message, and error location 

for each error found during input/output validation. 

For more information about validation errors, see Appendix G, “Validation Errors and 

Exceptions”. 

Validation Exceptions 

If you use the pub.schema:validate and pub.schema:validatePipeline services to perform data 

validation, you can determine whether the service should succeed or fail if the data being 

validated is invalid. You might want a service to succeed even if the data is invalid. In the 

pub.schema:validate and pub.schema:validatePipeline services, the value of the failIfInvalid input 

variable determines whether a service fails because of an invalid object. 

If the pub.schema:validate and pub.schema:validatePipeline service fails, webMethods Integration 

Server throws a validation exception. A validation exception is generated if one of the 

following is true: 

� Errors are detected in the object (XML node, pipeline, or document (IData object)) that 

is passed (for example, null value). 

� The basic validation contract is violated (for example, a binary tree is passed instead 

of a document (IData object) as expected). 

� You specify that the service should fail if the object to be validated (XML node, 

pipeline, or document (IData object)) did not conform to the IS schema or IS 

document type (for example, failIfInvalid = true). If this is the reason for the exception, 

webMethods Integration Server inserts the validation errors into the exception 

message. 


Running Out of Memory During Validation 


During validation of an XML node, a large maxOccurs value for an element in the IS 

schema used as the blueprint can cause an out of memory error or a stack overflow. To 

prevent a stack overflow or out of memory error, you can set a threshold value for 

maxOccurs. When the validation engine encounters a maxOccurs value greater than the 

threshold value, it proceeds as if the maxOccurs value was equal to 'unbounded'. 

To set a maxOccurs threshold value, you can edit the server configuration parameter 

watt.core.schema.maxOccursThresholdValue. By default, this parameter does not 

have a value. 

To set a maxOccurs threshold value 

1 Start webMethods Integration Server and open the Integration Server Administrator. 

2 In the Settings menu of the navigation area, click Extended. 

3 Click Edit Extended Settings. The server displays the Extended Settings screen. 

4 In the text area under Extended Settings, type 

watt.core.schema.maxOccursThresholdValue=value where value is the number 

you want to use as the maxOccurs threshold. 

5 Click Save Changes. 


Chapter 11. Testing and Debugging Services 

� Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

� Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

� Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 

� Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 

� Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 

� Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 

� Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 

� Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

� Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 

� Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 

� Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 


Testing and Debugging 

Testing Services 

11. Testing and Debugging Services 

Like other types of computer programming, developing a service is an iterative process of 

building, testing, and correcting (debugging) your code. 

Developer provides a range of tools to assist you during the testing and debugging 

phases. For example, you can: 

� Test services, specify their input values, and inspect their results. 

� Examine the call stack and the pipeline when an error occurs. 

� Execute services in “debug” mode, a mode that lets you monitor a flow service’s 

execution path and/or execute its steps one at a time. 

� Temporarily disable steps in a flow and/or specify points where you want to halt 

execution. 

Additionally, webMethods provides tools for collecting run-time information that can 

help debug a service. These include tools to: 

� Write arbitrary messages to the server log. 

� Trace the pipeline at run time. 

� Modify and save the contents of the pipeline at a specified point. 

Note: For information about testing triggers and publishable document types, see the 

Publish-Subscribe Developer’s Guide. 

You can test any type of service (flow services or coded services) with Developer, 

eliminating the need to build special clients simply for testing. It also allows you to easily 

pass different sets of test data to your service, which makes it easy to test your service 

under a variety of data conditions. 

You can use Developer to test services in two ways: 

� From Developer. With this technique, Developer is the client. That is, Developer invokes 

the service and receives the results. 

� From a browser. With this technique, Developer formulates the URL necessary to 

invoke the service and passes that URL to your browser. Your browser actually 

invokes the service and receives the results. When you develop services for browserbased 

clients (especially ones whose output will be formatted using output templates) 

you will want to test those services at least once using this technique. 


Testing Services from Developer 


In most cases, you will test your services using Developer (not a browser) as the client. 

You do this using the Run command on the Test menu. 

When you execute a service with the Run command, Developer invokes the service (just as 

an ordinary IS client would) and receives its results. The service executes once, from 

beginning to end (or until an error condition forces it to stop) on the server on which you 

have an open session. 

Before Developer invokes the service, it prompts you for input values. You can type the 

input values into the dialog box provided by Developer or load the values from a file that 

was saved during an earlier test. 

Results from the service are returned to Developer and displayed in the Results panel. 

This allows you to quickly examine the data produced by the service and optionally 

change it or save it to a file. You can use the saved data as input for a later test or to 

populate the pipeline during a debugging session. 

Note: If you selected the Switch to Test perspective check box on the Test page of the Options 

dialog box (Tools�Options), Developer displays the Test perspective when you begin 

testing a service. For more information about perspectives, see “Switching Perspectives” 

on page 36. 

To test a service using Developer as the client 

1 Open the service that you want to test. 

2 On the Test menu, select Run. If you have not yet saved changes to the service, 

Developer prompts you to save them. 

3 If the service has input parameters, type the input values for each variable in the Input 

dialog box or click the Load button to retrieve the values from a file. For more 

information, see “Entering Input for a Service” on page 278. 

4 If you want Developer to pass empty variables (variables that have no value) to the 

service, select the Include empty values for String Types check box. When you select this 

option, empty Strings are passed with a zero-length value. If you do not select this 

option, empty Strings are not passed to the service. 

5 If you want to save the input values that you have entered, click Save. Input values 

that you save can be recalled and reused in later tests. For more information about 

saving input values, see “Saving Input Values to a File” on page 280. 

6 Click OK. Developer invokes the service with the specified set of input values. 


You can enter 

simple Strings... 

...and complex 

documents and 

document lists. 

Notes: 


� If the service executes to completion, its results appear on the Results panel. For more 

information about the Results panel, see “Viewing the Results of the Service” on 

page 281. 

� If the service throws an exception, an error message displays. Click Details in the 

message box to view the call stack and the state of the pipeline where the error 

occurred. For more information about errors that occur while testing a service, see 

“Run-Time Exceptions” on page 284. 

Entering Input for a Service 

When you test a service with Developer, Developer displays the Input dialog box, which 

prompts you for input to the service. This dialog box contains an entry for each variable 

defined by the service’s input parameters. Object variables without constraints are noted 

as “Not editable by user.” 

You can also enter documents and document lists containing string-based children and 

constrained objects through the Input dialog box. 

Enter input values in the Input dialog box 

You can manually type your input values into the Input dialog box or, if you saved the 

input values from an earlier test, you can load them from a file. 



Note: If your service expects Object variables that do not have constraints assigned or an 

Object defined as a byte[ ], you will not be able to enter those values in the Input dialog 

box. To test these values in a service, you must also create a service that generates input 

values for your service. Then you need to construct a test harness (a flow service that 

executes both the service that produces the test data and the service you want to test) and 

use that harness to test your service. 

To enter values by typing them 

1 Open the service and execute it as described in “Testing Services from Developer” on 

page 277 or “Testing Services from a Browser” on page 286. 

2 For each variable listed in the Input dialog box, type an input value. If the service 

takes complex variables such as a String lists, documents, or document lists, use the 

following buttons to specify the variable's individual elements. 

Use this… To... 

Add a row to the variable. 

Insert a blank row above the currently selected row. 

Add a column to the variable. 

Delete the selected row from the variable. 

Delete the selected column from the variable. 

3 If you want Developer to pass empty Strings to the service, select the Include empty 

values for String Types check box. When you select this check box, empty Strings are 

passed with a zero-length value. If you do not select this check box, empty strings are 

not passed to the service. 

Note: When you enter values for constrained objects in the Input dialog box, Developer 

automatically validates the values. If the value is not of the type specified by the object 

constraint, Developer displays a message identifying the variable and the expected type. 


Saving Input Values to a File 


You can save values that you type in the Input dialog box to a file so that you can reuse 

them in later tests. 

When saving input values to a file, keep the following points in mind: 

� Empty variables (variables that do not have a value) are only saved if the Include empty 

values for String Types check box is selected. If you do not select this check box, 

Developer does not save empty variables in the file. 

� You can store the file in any directory that is accessible to the computer on which 

Developer is running. Because these files are not actual run-time components, they do 

not need to be saved in Integration Server’s namespace or even on the server machine 

itself. 

Note: You might want to consider creating an input file for each set of data that you 

routinely test your service against. This will provide you with a ready-made set of test 

cases against which to verify the service when it is modified by you or other 

developers in the future. Many sites establish a special directory on their development 

server just for holding sets of test data that they generate in this manner. 

To save input values that you have entered for a service 


page 277 or “Testing Services from a Browser” on page 286. 

2 Enter input values into the Input dialog box as described in “Entering Input for a 


3 When you are finished entering values, click Save. 

4 In the Save File dialog box, specify the name of the file to which you want the values 

saved. 

Loading Input Values from a File 

You can reload input values that you have saved to a file instead of rekeying the values in 

the Input dialog box. To do this, click the Load button in the Input dialog box and then 

select the file that contains the input values you want to use. 

When you use input values from a file, keep the following points in mind: 

� Developer only loads variables whose name and type match those displayed in the 

Input dialog box. Variables that exist in the file, but not in the dialog box, are ignored. 

In the case of Object variables without constraints or Object variables of type byte [], 

the values in the file are not used. 

� Values from the file replace those already in the Input dialog box. 


To examine the 

contents of a variable, 

select it in the top 

pane... 

...and view it in the 

bottom pane. 


� Variables that exist in the Input dialog box, but not in the file, are set to null. 

� Besides loading values that were saved from the Input dialog box, you can also load 

values that were saved using pub.flow:savePipelineToFile service or the Save Pipeline 

commands on the File menu. In addition, you can change values in the pipeline during 

testing. For information about saving the state of the pipeline, see “Saving and 

Restoring the Pipeline” on page 303. For information about modifying values in the 

pipeline, see “Modifying the Current Pipeline” on page 302. 

To load input values that have been saved to a file 


page 277. 

2 When the Input dialog box appears, click Load. The Load File dialog box appears. 

3 Select the file containing the input values that you want to load. 

Viewing the Results of the Service 

When you execute a service with the Run command or with one of Developer’s debugging 

tools, its results are displayed in the Results panel. 

Results from a service you run in Developer are displayed in the Results panel 



The upper half of the Results panel displays all the variables in the pipeline. To view the 

contents of a particular variable, you select the variable in the upper half. Its contents are 

shown in the lower half. 

When viewing the Results panel, keep the following points in mind: 

� The Results panel represents the contents of the pipeline. 

� The Results panel shows all variables placed in the pipeline by the service, not just 

those that were declared in the service’s input/output parameters. 

� Variables that a service explicitly drops from the pipeline do not appear on the Results 

panel. 

� You can browse the contents of the Results panel, but you cannot edit it directly. 

� You can save the contents of the Results panel to a file and use that file to restore the 

pipeline at a later point. For additional information about saving and restoring the 

contents of the Results panel, see “Saving and Restoring the Pipeline” on page 303. 

� If you run a service and an error occurs, results are not displayed in the Results panel. 

However, you can click the Details button in the error message box to examine the state 

of the pipeline at the point where the exception occurred. 

� When debugging a flow service in step mode, you can use the Results panel to 

examine the state of the pipeline after each flow step. You can optionally load a 

different pipeline or modify the existing pipeline between steps. For information 

about loading a pipeline in the Results panel, see “Saving and Restoring the Pipeline” 

on page 303. For information about modifying an existing pipeline, see “Modifying 

the Current Pipeline” on page 302. 

� When you use a breakpoint or the Trace to Here command to halt execution of a flow 

service, you can use the Results panel to examine the pipeline at that point where you 

halted the flow. You may also optionally load a different pipeline or modify the 

existing pipeline at this point. For information about loading a pipeline in the Results 

panel, see “Saving and Restoring the Pipeline” on page 303. For information about 

modifying an existing pipeline, see “Modifying the Current Pipeline” on page 302. 

� Variables whose object types are not directly supported by the Developer will appear 

in the Results panel, but because Developer cannot render the values of such objects, a 

value does not appear in the Value column. Instead, the Value column displays the 

object’s Java class message. 

� Variables that contain com.wm.util.Table objects appear as document lists in the Results 

panel. 


Copying Variables from the Results Panel 


You can use the Copy command to copy information from the Results panel and paste it 

into other fields in Developer. The information that Developer inserts when you paste an 

element from the Results panel depends on the field into which you paste it. 

If you paste to a field that expects… Developer inserts… 

A data definition (for example, the 

Pipeline tab, the Input/Output tab, or a 

document (IData object)) 

1 Display the Results panel and select the element that you want to copy. (When 

copying elements from the lower half, you can select a group of contiguous elements 

by pressing the SHIFT key and selecting the first and last element in the group that 

you want to copy.) 

2 On the Edit menu, click Copy. 

The copied element's data definition. 

The name of an element The copied element’s name (and position if it 

is a member of a complex element such as a 

String table, document (IData object), or 

document list (IData [ ])). 

To copy and paste elements from the Results panel 

3 Select the field into which you want to paste the information, then click Edit�Paste 

After. (If the Paste command is not available, it indicates that the information cannot be 

pasted into the selected field.) 


...to display the call 

stack and the 

pipeline. 

Run-Time Exceptions 


If a service that you run from Developer throws an exception, Developer reports the error 

in a following message box. 

You can click the Details button to display the call stack and the pipeline at the point where 

the error occurred. 

The Details button shows the call stack and the pipeline 

Note: You can improve performance and memory usage in Developer by caching elements, 

such as services and schemas. For details, see “Caching Elements” on page 70. 


This service threw 

the exception. 

This service threw 

the exception. 

The Call Stack 


The call stack identifies which flow step generated the error and lists its antecedents. For 

example, let’s say you have a service called PARENT that invokes three services, CHILD_A, 

CHILD_B, and CHILD_C. If CHILD_B is a Java service and it throws an exception, the call stack 

will look like this: 

Call stack from a nested service 

Now let’s assume that CHILD_B is a flow service that calls three Java services: CHILD_B1, 

CHILD_B2, and CHILD_B3. If CHILD_B3 throws an exception, the call stack will look like this: 

Call stack from a deeply nested service 



Note that the call stack is LIFO based. That is, the top entry in the stack identifies the last 

(that is, most recent) service invoked. The bottom entry identifies the parent service (the 

one that you originally invoked from Developer). If the parent itself throws the exception, 

it will be the only entry in the call stack. 

Note: Services invoked from within a Java service are not reported in the call stack, even if 

they throw the exception. 

The Pipeline Dump 

The Service Failures Detail dialog box contains the contents of the pipeline at the point of 

failure. Note that when a failure occurs within a Java service, the Pipeline area represents 

the state of the pipeline at the point when that service was initially called. If the Java 

service made changes to these values before throwing the exception, those changes will 

not be reflected in the Pipeline information. 

Testing Services from a Browser 

You can use the Run in Browser command in Developer to test a service from a browser 

(that is, to simulate a browser-based client). When you use this command, Developer 

prompts you for the service’s input values, builds the URL necessary to invoke the service 

with the inputs you specify, and then passes the URL to your browser. When you use this 

command to test a service, your browser (not Developer) actually invokes the service and 

receives its results. 

If you are developing services that will be invoked by browser-based clients, particularly 

ones whose output will be formatted using output templates, you will want to test those 

services using the Run in Browser command to verify that they work as expected. 

To test a service using a browser as the client 


2 On the Test menu, click Run in Browser. If you have unsaved edits, Developer prompts 

you to save them. 

3 If the service has input parameters, type the input values for each variable in the Input 

dialog box or click the Load button to retrieve the values from a file. For more 

information, see “Entering Input for a Service” on page 278. 

Note: Only Strings and String lists are passed to the browser. 

4 If you want to pass empty variables (variables that have no value) to the service, select 

the Include empty values for String Types check box. When you select this option, empty 



Strings are passed with a zero-length value. If you do not select this option, Developer 

excludes empty variables from the query string that it passes to the browser. 

5 If you want to save the input values that you have entered, click Save. Input values 

that you save can be recalled and reused in later tests. For more information about 

saving input values, see “Saving Input Values to a File” on page 280. 

6 Click OK. Developer builds the URL to invoke the service with the inputs you have 

specified, launches your browser, and passes it the URL. 

� If the service executes successfully, its results appear in your browser. (If an 

output template is assigned to the service, the template will be applied to the 

results before they are returned.) 

� If the service experiences an error, an error message is displayed in the browser. 

Testing Services that Expect XML Documents as Input 

If your service expects an XML document as input (that is, it takes a node as input), you 

can test it using the Send XML File command. This command prompts you for the name of 

the XML file and submits the file to the service, emulating the way in which the service 

would execute if an XML document were posted to it. 

To test a service by sending an XML file to the service, you must have Read access to the 

service. 

To test a service that expects an XML document as input 


2 From the Test menu, select Send XML File. If you have unsaved edits, Developer 

prompts you to save them. 

3 In the Select Test Mode dialog box, specify whether you want the service to run in 

Trace mode or Step mode and click OK. 

4 In the Select File dialog box, select the XML file that you want to submit to this service 

and click OK. Developer submits the file to the server, which parses it into a node object 

and passes it to selected service. 

� If the service executes to completion, its results appear on the Results panel. For 

more information, see “Viewing the Results of the Service” on page 281. 

� If the service experiences an error, an error message displays. Click Details in the 

message box to view the call stack and the state of the pipeline where the error 

occurred. For additional information about errors that occur while testing a 

service, see “Run-Time Exceptions” on page 284. 


Working in Debug Mode 


When you use Developer to execute a service using the Run or Run In Browser commands, it 

executes as a normal service. That is, the server does not execute it any differently than it 

would if any other client requested it. However, Developer also allows you to test a 

service in debug mode, a mode that allows you to monitor the execution path of a flow 

service and/or move through its steps one at a time. 

When you run a flow service in debug mode, it is executed in a special way that returns 

results and other debugging information back to Developer after each step. 

Note: You can only debug one flow service at a time. 

Entering Debug Mode 

You automatically enter debug mode when you select any of the following commands 

from the Test menu: 

Command Description 

Trace Executes flow steps one after another to the end of the service and 

visually marks steps as they execute. For information about using 

this command, see “Using the Trace Tools” on page 290. 

Trace to Here Executes flow steps one after another up to a specified point and 

visually marks steps as they execute. For information about using 

this command, see “Using the Trace Tools” on page 290. 

Trace Into Executes flow steps one after another to the end of the service and 

visually marks steps as they execute, including steps in child 

flows. For information about using this command, see “Tracing 

into a Child Flow” on page 292. 

Step Executes the next flow step and then halts. For information about 

using this command, see “Using the Step Tools” on page 292. 

Step Into Opens a child flow or a MAP step so that you can debug the 

individual flow steps within it. For information about using this 

command, see “Stepping though a Child Flow” on page 294 and 

“Using the Step Tools with a MAP Step” on page 294. 

Important! The debug commands are only available for flow services. When a Java service 

is selected, these commands are not available. 

When you first enter debug mode, processing always starts from the first step in the flow 

service. Completed steps are marked with a gray outline. A step that is “in process” or is 


This BRANCH target 

was executed with its 

respective nested 

steps. 

The results of this step 

are currently on the 

Results panel. 

This step will be 

executed next. 


the next in line to be processed is marked with a green outline. When you step though a 

flow service or you halt execution using a breakpoint or the Trace to Here command, the 

green outline indicates which step will execute when you resume processing. 

Tip! You can remove the gray and green trace lines by using the Test�Reset command. 

Note, however, that this will also end your debugging session. 

The following example shows a flow service that is being executed using the Step 

command. As you can see, the BRANCH on ‘PaymentType’ step has three targets. The gray 

outline shows which path was executed. The green outline indicates that BRANCH on 

‘/AuthorizationCode’ is the step that will execute when the next Step command is performed. 

Debug mode visually shows you the service’s execution path 

Combining the Step and Trace Commands in Debug Mode 

Once you enter debugging mode, you can switch among the different debugging 

commands and examine certain segments of the service more closely than others. For 

example, you might want to execute the first few steps of a service with the Step command 

and then simply trace the remainder. Or, you might want to use Trace to Here to execute to 

a particular point and then execute the remaining flow steps in the service one step at a 

time. 



When you combine techniques, remember that the flow step outlined in green always 

indicates the current point of execution and marks the next flow step that will execute 

when you resume processing. 

Resetting Debug Mode 

The Test�Reset command resets debug mode. You must use this command when you 

want to begin debugging the same service again from the beginning of the flow. The 

following actions also reset a debugging session: 

� Executing the Run command 

� Refreshing Developer’s session on the server 

� Editing the flow service 

� The service throws an exception 

When a session is reset, trace lines are cleared and the point of execution is set back to the 

top of the flow service. 

The following actions do not reset a debugging session: 

� Setting breakpoints 

� Examining the contents of any of the other tabs associated with the service 

� Saving or restoring the contents of the Results panel 

Using the Trace Tools 

If a flow service has a complex path of execution (for example, it contains many branching 

sequences), it is often useful to simply see which path was taken when the flow executed. 

The trace tools, Trace, Trace to Here, and Trace Into, allow you to do this. They visually mark 

the flow steps that are executed within a flow service. 

If you want to... Use... 

Trace to the end of the service without tracing child services 

(breakpoints are ignored in this mode) 

Trace to a specified point in the service without tracing child 

services (breakpoints are ignored in this mode) 

Trace to the end of the service or the next breakpoint, including the 

paths of all child services that this service invokes 


Trace 

Trace to Here 

Trace Into


Note: To trace through a top-level service, you must have Execute, Read, and List access to 

the service. To trace through all the services within a top-level service, you must have 

Execute, List, and Read access to all services that the top-level service invokes. For more 

information about ACLs and the trace tools, see “ACLs and Testing/Debugging Services” 

on page 118. 

To trace to the end of a service 

1 Open the service that you want to trace. 

2 On the Test menu, click Trace. 

� If the service is already in debug mode, Developer traces the remaining steps, 

starting from the current point of execution (the step outlined in green.) 

� If the service is not in debug mode, Developer starts the trace at the top of the 

flow. If you have any unsaved changes, Developer prompts you to save those 

changes before it starts the trace. If the service takes input, you will be prompted 

for its input values. 

To trace to a specified point 

1 Open the service that you want to trace. 

2 In the editor, select the flow step up to which you want to trace. (Developer will trace 

all steps up to, but not including, the one you select.) 

Note: If the point to which you want to trace resides in a child of the service that you 

are testing, you must use the breakpoint feature to trace to that point. For information 

about setting breakpoints, see “Setting Breakpoints” on page 295. 

3 On the Test menu, click Trace to Here. 

� If the service is already in debug mode, Developer starts at the current point of 

execution (the step outlined in green) and traces to the selected step. If the 

selected step is before the current point of execution, the trace starts at the top of 

the flow. 


flow service and traces to the selected step. If you have any unsaved changes, 

Developer prompts you to save those changes before it starts the trace. If the 

service takes input, you will be prompted for its input values. 



4 When Developer reaches the selected flow step, it halts. At this point, you may do any 


� Examine the contents of the Results panel. 

� Modify, save, and/or restore the contents of the Results panel. 

� Use Step or Step Into to execute subsequent flow steps one at a time. 

� Select another step in the flow service and use Trace to Here to trace to that point. 

� Select Trace to trace the remainder of the service. 

� Select Reset to clear the debugging session and reset the starting execution point 

to the top of the service. 

Tracing into a Child Flow 

Many times, the service you are debugging invokes other flow services (child services). In 

these cases it is useful to trace the execution paths of the child services as well as the 

parent that you are testing. You do this with the Trace Into command. 

When you initiate a trace with Trace Into, Developer automatically opens and traces the 

individual steps in every child flow that the parent invokes, including the children of the 

child services if there are any. 

To trace into a child service 

1 Open the parent service that you want to test. 

2 On the Test menu, click Trace Into. 

� If the service is already in debug mode, Developer starts the trace at the current 

point of execution (the step outlined in green) and traces the service and its 

children until it reaches a breakpoint or the end of the flow. 


flow and traces the service and its children until it reaches a breakpoint or the end 

of the flow. If you have any unsaved changes, Developer prompts you to save 

those changes before it starts the trace. If the service takes input, you will be 

prompted for its input values. 

Using the Step Tools 

You use the Step, Step Into, and Step Out commands on the Test menu to interactively 

execute a flow service one flow step at a time. Stepping through a flow is an effective 

debugging technique because it allows you to examine (and optionally modify) the data 

in the pipeline before and after each step. Additionally, if you are trying to isolate an error, 

step mode can quickly help you pinpoint the offending flow step. 



If you want to... Use... 

Execute the current flow step (the one with the green outline) Step 

Open a child flow so that you can debug the individual flow steps 

within it 

Step Into 

Return to the parent flow from a child that you have stepped into Step Out 

Note: To step through a top-level service, you must have Execute, Read, and List access to 

the service. To step through all the services within a top-level service, you must have 

Execute, List, and Read access to all services that the top-level service invokes. For more 

information about ACLs and the step tools, see “ACLs and Testing/Debugging Services” 

on page 118. 

Note: When you step into a child flow, Developer displays the child flow in the editor. 

Note that at any point while stepping through a flow service, you can do any of the 

following: 

� Examine the contents of the Results panel. 

� Modify, save, and/or restore the contents of the Results panel. 

� Select a step in the flow service and use Trace to Here to trace to that point. 

� Select Trace to trace the remainder of the service. 

� Select Reset to clear the debugging session and reset the starting execution point to the 

top of the service. 

To step through a flow service 

1 Open the service that you want to step through. 

2 On the Test menu, click Step. 

� If the service is already in debug mode, Developer executes the current step (the 

step outlined in green) and then stops. 

� If the service is not in debug mode, Developer enters debug mode and selects the 

first step in the flow service. To execute that flow step, select Step again. If you 

have any unsaved changes, Developer prompts you to save those changes before 

it enters debug mode. If the service takes input, you will be prompted for its input 

values. 


Stepping though a Child Flow 


Many times, the flow service you are debugging invokes other flow services (child 

services). In these cases it is useful to step through the individual flow steps within a child 

service, too. You do this with the Step Into and Step Out commands. 

To step into and out of a child flow 

1 Select the parent flow service and step or trace to the flow step that invokes the child 

flow. See “To step through a flow service” on page 293 or “To trace to a specified 

point” on page 291 if you need procedures for this step. 

2 On the Test menu, click Step Into. Developer opens the child flow service and selects 

(but does not execute) the first step. 

3 On the Test menu, click Step to execute the first step in the child service. Repeat this 

step for each flow step that you want to individually execute within the child. 

4 If you want to return to the parent flow service without stepping through the entire 

child, click Step Out from the Test menu. This command will trace the remaining steps 

in the child flow, return to the parent, and then select (but not execute) the next step in 

the parent flow. 

Notes: 

� While you are debugging the child, you may use Trace to Here or set a breakpoint 

to execute up to particular point in the child. 

� If you select Trace or Trace Into while you are debugging the child, Developer traces 

the remaining steps in the child and returns to the parent automatically. 

� If you select Step on the last step in the child flow service, Developer 

automatically returns you to the parent. 

� You can use Step Into to step into a child flow that is nested within a child that you 

have stepped into. 

� If you select Step Into on a step that is not a flow service, Step is executed. 

Using the Step Tools with a MAP Step 

You can use the Step Into and Step Out commands to debug individual transformers in a 

MAP step. 



1 Select the parent service that contains the MAP step and then step or trace to the MAP 

step. (That is, make the MAP step the current flow step. Developer indicates this by 

outlining the step in green.) See “To step through a flow service” on page 293 or “To 

trace to a specified point” on page 291 if you need procedures for this step. 

2 On the Test menu, click Step Into. Developer selects on the Pipeline tab (but does not 

execute) the first transformer in the MAP step. 

3 On the Test menu, click Step to execute the first transformer. Repeat this step for each 

transformer that you want to individually execute within the MAP step. 

4 If you want to return to the parent without stepping through the entire MAP, select 

Step Out from the Test menu. This traces the remaining transformers in the MAP, 

returns to the parent, and selects (but does not execute) the next step in the parent 

flow. 

Notes: 

Setting Breakpoints 

To step into and out of a MAP step 

� If you select Trace or Trace Into while you are debugging the MAP, Developer traces 

the remaining steps in the MAP and returns to the parent automatically. 

� If you select Step on the last transformer in the MAP, Developer automatically 

executes that transformer and returns you to the parent flow. 

� You can use Step Into to step into a transformer that is a flow service. 

� If you select Step Into on a transformer that is not a flow service, Step is executed. 

A breakpoint is a point in a flow service where you want processing to halt when you 

execute that flow service with certain debug modes. Breakpoints can help you isolate a 

section of code or examine data values at a particular point in the execution path. For 

example, you might want to set a pair of breakpoints before and after a particular segment 

of a flow so that you can examine the pipeline on the Results panel before and after that 

segment executes. 

When working with breakpoints, keep the following points in mind: 

� Breakpoints are not persistent. They exist only during the life of the Developer session 

on the current server in which you set them. When you close Developer or refresh the 

session on the current server, your breakpoints are cleared. (Note that resetting debug 

mode does not clear your breakpoints.) 

� Breakpoints are also local to your Developer session on the current server. Breakpoints 

that you set on your machine do not affect other developers or users who might be 

executing or debugging services in which you have set breakpoints. 



� Breakpoints are only recognized when you execute a service with the Trace Into 

command from Developer. If you execute a service using any of the other testing or 

debugging commands, breakpoints are ignored. 

� If you are caching services by using the General area of the Options dialog box, and 

your flow service has a breakpoint, you cannot clear the cache of the flow service until 

the breakpoint is removed. For more information about caching, see “Configuring a 

Service’s Use of Cache” on page 138. 

� To set a breakpoint in a service, you must have Read access to a service. However, if 

the service is invoked within another service (a top-level service) to which you have 

Read access, you can set a breakpoint on the service within the top-level service. 

What Happens When a Breakpoint Is Encountered? 

When you execute a service that contains a breakpoint or call a child service that contains 

a breakpoint, the service is executed up to, but not including, the designated breakpoint 

step. At this point, processing stops and will not resume until you select another one of 

Developer’s debugging commands. (Remember, if you want Developer to stop at 

subsequent breakpoints, you must select the Trace Into command.) 

To set a breakpoint on a flow step 

1 Open the flow service in which you want to set a breakpoint. 

2 In the editor, select the step that will function as the breakpoint. (During debugging, 

processing will halt immediately before this step). 

3 On the Test menu, click Set Breakpoint. The step’s icon turns red, indicating that it is a 

breakpoint. 

To clear a breakpoint from a flow step 

1 Open the flow service in which you want to clear a breakpoint. 

2 In the editor, select the breakpoint step. 

3 On the Test menu, click Clear Breakpoint. The step’s icon returns to its normal color, 

indicating that it is no longer a breakpoint. 

–OR– 

1 On the Test menu, click Breakpoints to display the current list of breakpoints on the 

current server. 

2 In the list, select the breakpoint that you want to clear. 

3 Click Remove. 


Setting Breakpoints on Transformers 


You can set a breakpoint on a transformer in a MAP step. When you execute a service that 

contains a breakpoint or calls a service that contains a breakpoint on a transformer, the 

service is executed up to, but not including, the designated breakpoint transformer. 

Note: Transformers in a MAP step execute in an arbitrary order. You cannot assume an 

order of execution. Consequently, some of the transformers in the MAP step might 

execute before Developer reaches the breakpoint, even if the transformers appear below 

the breakpoint on the Pipeline tab. Likewise, transformers above the breakpoint might not 

execute before the breakpoint is encountered. (These will execute when you resume 

tracing.) Executed transformers have a gray outline. 

To set a breakpoint on a transformer 

1 Open the flow service in which you want to set a breakpoint. 

2 In the editor, select the MAP step containing the transformer that will function as the 

breakpoint. 

3 On the Pipeline tab, select the transformer that will function as the breakpoint. (During 

debugging, processing will halt immediately before this transformer.) 

4 On the Test menu, select Set Breakpoint. The icon appears next to the transformer 

name, indicating that it is a breakpoint. 

To clear a breakpoint on a transformer 

1 Open the flow service in which you want to clear a breakpoint. 

2 In the editor, select the MAP step that contains the transformer from which you want 

to clear a breakpoint. 

3 On the Pipeline tab, select the transformer from which you want to clear a breakpoint. 

4 On the Test menu, click Clear Breakpoint. Developer removes the icon next to the 

transformer name. 

–OR– 

1 On the Test menu, click Breakpoints to display the current list of breakpoints on the 

current server. 

2 In the list, select the breakpoint that you want to clear. 

3 Click Remove. 


Viewing a List of Breakpoints 


Use the following procedure to view the list of breakpoints that are currently set in your 

Developer session. From this list, you can also clear and/or go to specific breakpoints. 

1 On the Test menu, click Breakpoints. 

2 If you want to go to a specific breakpoint, select it and then click Go to Breakpoint. 

3 If you want to clear a breakpoint, select it and then click Remove. 

Disabling Flow Steps, Transformers, and Conditions 

Disabled steps appear 

dimmed in the editor. 

To display the list of current breakpoints 

Note: Remember, breakpoints are not persistent. They only exist during the Developer 

session on the current server in which you set them. When you refresh or close your 

session on the current server, your breakpoints are cleared. 

When testing and debugging services, you can disable flow steps and transformers. You 

can also disable the condition placed on a link between variables on the Pipeline tab. The 

follow sections provide more information about disabling each of these items. 

Disabling Flow Steps 

You use the Compose�Disable Step command to disable a step in a flow service. Steps that 

you disable are not executed at run time. 

Disabled steps appear dimmed when viewed in Developer. If you disable a parent step 

(for example, a LOOP or a BRANCH), its children are also automatically disabled. If you 

disable a MAP step, the transformers in the MAP step are also automatically disabled. 

Disabled steps are not executed at run time 



Disabling a step is useful in many testing and debugging situations. For example, you 

might want to disable one or more steps to isolate a particular segment of a flow, similar to 

the way you might “comment out” a section of source code in a program you are testing. 

Be aware that disabling a step sets a persistent attribute that is saved in the flow service. 

Once you disable a step, it remains disabled until you explicitly re-enable it with 


Important! The run-time effect of disabling a step is the same as deleting it. Disabling a key 

step or forgetting to re-enable a disabled step can break the logic of a service and/or cause 

the service to fail. Developer allows you to disable any step in a flow service, but it is your 

responsibility to use this feature carefully. 

To disable a step in a flow service 

1 Open the flow service that you want to edit. 

2 In the editor, select the step that you want to disable. 

3 On the Compose menu, click Disable Step. 

The step dims, indicating that it is disabled. 

To enable a step in a flow service 


2 In the editor, select the disabled step that you want to re-enable. 

3 On the Compose menu, click Enable Step. 

Disabling Transformers 

You can also use the Compose�Disable Step command to disable a transformer in a MAP 

step. Transformers that you disable are not executed at run time. In fact, webMethods 

Integration Server does not execute any of the links between pipeline variables and the 

variables for a disabled transformer. 

Disabled transformers appear dimmed when viewed in Developer. 


Transformers that are 

disabled appear dimmed 

on the Pipeline tab. 

Disabled transformers are not executed at run time 



Note: When you disable the MAP step, Developer automatically disables all of the 

transformers in a MAP step 

Important! The run-time effect of disabling a transformer is the same as deleting it. 

Disabling a transformer or forgetting to re-enable a disabled transformer can break the 

logic of a service and/or cause the service to fail. Although Developer allows you to 

disable any transformer or step in a flow service, use this feature carefully. 

To disable a transformer in a MAP step 

2 In the editor, select the MAP step containing the transformer that you want to disable. 

3 On the Pipeline tab, select the transformer you want to disable. 

4 On the Compose menu, click Disable Step. 

The transformer dims, indicating that it is disabled. 


To enable a transformer in a MAP step 



2 In the editor, select the MAP step containing the disabled transformer that you want 

to enable. 

3 On the Pipeline tab, select the disabled transformer that you want to enable. 

4 On the Compose menu, click Enable Step. 

Disabling a Condition Placed on a Link Between Variables 

When you link variables to each other, you can apply a condition to the link that connects 

the variables. At run time, this condition needs to be true for the value of the source 

variable to be copied to the target variable. During testing and debugging, you might 

want to disable or remove the condition from the link to make sure that Developer 

properly copies data between variables. By disabling the condition, you instruct 

Developer to ignore the condition placed on the link and automatically execute the link 

(copy the value from the source variable to the target variable). 

Disabling the condition preserves the written expression. When you enable the condition, 

you do not need to rewrite the expression. 

The Pipeline tab uses a blue link (line) to indicate that properties (such as conditions and 

array indexes) have been applied to the link between variables. Developer retains the blue 

color even when you disable the applied condition to remind you that properties have 

been set. 

To disable a condition placed on a link between variables 


2 In the editor, select the INVOKE or MAP step that contains the link with the condition 

you want to disable. 

3 On the Pipeline tab, select the link with the condition that you want to disable. 

4 In the General category of the Properties panel, set the Evaluate copy condition property 

to False. 

To enable a condition placed on a link between variables 


2 In the editor, select the INVOKE or MAP step containing the link with the condition 

you want to enable. 



3 On the Pipeline tab, select the link with the condition that you want to enable. 

4 In the General category of the Properties panel, set the Evaluate copy condition property 

to True. 

Modifying the Current Pipeline 

During debugging, you can modify the contents of the pipeline and submit those changed 

values to the next step in the flow service. For example, if you want to see the effect that 

different values for a variable have on the rest of the service, you can modify the values in 

the pipeline temporarily and continue debugging. You can also drop values from the 

pipeline. This functionality is useful for debugging. 

When modifying the pipeline, keep the following points in mind: 

� You can only modify the pipeline when a subsequent step in the service exists to 

which to pass the pipeline values. For example, if you use Trace for the entire service, 

you cannot modify the values of the pipeline after the service ends. However, if you 

use Step to debug the service, you can modify the pipeline values for the next step in 

the service. 

� You cannot modify the values of unconstrained Objects and Object lists. However, 

you can drop them from the pipeline. 

� You cannot modify the values of recursive documents at the top level. However, you 

can expand the document and set values at the individual element level. 

� When you modify values or drop variables from the pipeline, the changes only apply 

to the current debugging session. The service is not permanently changed. 

� You can only modify or drop existing variables. You cannot add new variables to the 

pipeline. 

� You cannot use a larger editor or have a password field when you modify String 

values in the pipeline. 

To modify values in the current pipeline 

1 Use the Step, Step Into, or Trace to Here command to load values into the pipeline for the 

current step. 

2 In the Results panel, select the name of the variable for which you want to change the 

value. 

3 Right-click and select Modify Value. 

4 In the Modify Value dialog box, type the new pipeline value for the variable. 


5 Click OK. The value is changed in the Results panel. 


6 To debug the rest of the service with the new pipeline value, use the Step, Step Into, or 

Trace to Here command. Keep in mind that the value is only changed for the current 

debugging session; it is not changed permanently. 

To drop values from the current pipeline 

1 Use the Step, Step Into, or Trace to Here command to load values into the pipeline for the 

current step. 

2 In the Results panel, select the name of the variable that you want to drop from the 

pipeline. 

3 Right-click and select Drop. The variable disappears from the Results panel. 

4 To debug the rest of the service with the dropped pipeline value, use the Step, Step Into, 

or Trace to Here command. Keep in mind that the value is only dropped for the current 

debugging session; it is not dropped permanently. 

Saving and Restoring the Pipeline 

Because the pipeline contains the data that a service operates against, the ability to save 

and restore the pipeline when you are debugging a service is something you may 

frequently want to do. For example, if a service is failing intermittently at run time, you 

may want to insert steps to save the pipeline at various points in the service so you can 

capture and examine the data that it was running against after a failure. 

Saving the Results 

You can save the pipeline to a file, which you can use to restore the pipeline to its current 

state at a later point in time. This is useful when you want to test another service against 

the current set of pipeline values or if you want to restore the pipeline to this exact state 

later in the debugging process. There are two ways to save the contents of the pipeline: 

� You can manually save the contents of the Results panel when you run or debug a 

service using Developer. 

� You can programmatically save the pipeline at run time by invoking 

pub.flow:savePipelineToFile at the point where you want to capture the pipeline. 

When you save a pipeline, it is saved in a file in XML format. The file you create can be 

used to: 

� Manually load the pipeline into Developer’s Results panel. 

� Dynamically load the pipeline at run time using the pub.flow:restorePipelineFromFile 

service. 



� Load a set of input values into the Input dialog box when testing a service with 


You can view a pipeline file with an ordinary text editor. When saving the pipeline, keep 

the following points in mind: 

� Only XML-codable variables are saved. This includes, Strings, String lists, String 

tables, documents, and document lists. Variables that are not XML codable are not 

saved. 

� Empty variables and null variables are saved. 

Saving the Contents of the Results Panel 

Use the following procedure to save the contents of the Results panel to a pipeline file. 

To save the contents of the Results panel 

1 Display the Results panel and click anywhere within it. 

2 Right-click and select one of the following commands: 

To… Select this command… 

Save the file to your local file system. 

Note: If you intend to use the pipeline file to dynamically 

restore the pipeline using pub.flow:restorePipelineFromFile, use 

Save Pipeline to Server to save the file to the server (see 

below). 

Save the file to the pipeline directory on webMethods 


Select this command if you want to use the file to 

dynamically restore the pipeline at run time using the 

pub.flow:restorePipelineFromFile service. 

Save Pipeline Locally 

Save Pipeline to Server 



3 Depending on your action in the previous step, do one of the following: 

If you selected… Do this to specify the file name… 

Save Pipeline Locally Select the directory in which you want the file saved and 

assign a name to the file. 

Save Pipeline to Server Specify the name of the file in which you want the pipeline 

saved. By default, Developer saves the file to 

webMethods6\IntegrationServer\pipeline, which is 

where the restorePipelineFromFile service expects pipeline 

files. If you specify a relative path in the file name, the 

path is understood to be relative to the pipeline directory. 

Saving the Pipeline at Run Time 

Use the following general steps to save the pipeline programmatically. You can use this 

technique to capture the pipeline from a flow service or within a Java service. 

1 Open the service. 

2 Invoke pub.flow:savePipelineToFile at the point where you want to save a copy of the 

pipeline. 

3 Set the following parameter: 

Key Description 

filename A string that specifies the name of the file to which you want 

the file saved. If you do not specify a fully qualified path, the 

file is saved relative to 

webMethods6\IntegrationServer\pipeline. 

4 Save the service. (If you are using your own IDE, you will need to recompile the 

service, reregister it on the Integration Server, and reload its package.) 

5 Execute the service. 

For additional information about pub.flow:savePipelineToFile, see the webMethods Integration 

Server Built-In Services Reference. 


Restoring the Pipeline 


Pipeline values that you have saved to a file in the following ways can be used to restore 

the pipeline: 

� From the Developer’s Results panel with the Save Pipeline commands. 

� With the pub.flow:savePipelineToFile service at run time. 

� From the Input dialog box when you are testing a service with Developer. 

Restoring a pipeline is useful when you simply want to inspect the values in a particular 

pipeline file (perhaps one that contains the pipeline from a failed service). Additionally, it 

is useful in many testing situations. For example, you can use it to replace the existing 

pipeline with a different set of values when stepping though a flow service with the 

debugging tools. 

There are two ways to restore the contents of the pipeline: 

� You can manually load the saved pipeline into the Results panel in Developer. 

� You can programmatically load a saved pipeline at run time by invoking 

pub.flow:restorePipelineFromFile at the point where you want to modify the pipeline. 

Loading a Saved Pipeline into the Results Panel 

Use the following procedure to load a pipeline file into the Results panel. 

When you load a pipeline file into the Results panel, the contents of the pipeline file 

completely replaces the current pipeline. If you want to merge the contents of the file with 

the existing pipeline, use the pub.flow:restorePipelineFromFile service instead and set its merge 

parameter to “true.” For procedures, see “Loading a Saved Pipeline at Run Time” on 

page 307. 

To load a pipeline file into the Results panel 

1 Display the Results panel. (If you simply want to inspect a saved pipeline, create a 

new, empty flow service and display its Results panel.) 

2 Right-click and select one of the following commands: 

To... Select... 

Load a pipeline file from your local file system Restore pipeline locally 

Load a file that resides in the default pipeline directory 

on webMethods Integration Server 

Restore pipeline from 

Server 



3 Depending on your action in the previous step, do one of the following: 

If you selected... Do this to specify the file name... 

Restore Pipeline Locally Select the file that you want to load. 

Restore pipeline from 

Server 

Loading a Saved Pipeline at Run Time 

Use the following general steps to load a pipeline file programmatically. You can use this 

technique from a flow service or from a Java service. 

1 Open the service. 

2 Invoke pub.flow:restorePipelineFromFile at the point where you want to load the pipeline 

file. 

3 Set the following parameters: 



service, reregister it on webMethods Integration Server, and reload its package.) 


Specify the name of the file that you want to load. 

Developer retrieves the file from 

webMethods6\IntegrationServer\pipeline. 

filename A String that specifies the name of the pipeline file. If you do 

not specify a fully qualified path, the file is assumed to be 

relative to webMethods6\IntegrationServer\pipeline. For 

example, if you set filename to “badPipeline.xml”, 

restorePipelineFromFile expects to find that file in 

webMethods6\IntegrationServer\pipeline\badPipeline.xml. 

merge A String that specifies whether you want the contents of the 

file to replace or be merged with the existing pipeline. 

Set merge to... To... 

false Replace the existing pipeline with the one 

from the file. 

true Merge the contents of the file into the existing 

pipeline. 

For additional information about pub.flow:restorePipelineFromFile, see the webMethods 

Integration Server Built-In Services Reference. 


Other Debugging Techniques 


This section describes additional tools and techniques you can use to obtain run-time 

information that is useful for debugging a service. 

Using the Server’s Debug Facility 

webMethods Integration Server maintains a log file in which it records information about 

activity on the server. This log file resides in: 

webMethods6\IntegrationServer\logs\serveryyyymmdd.log 

The log contains information about actions that the server executes, such as loading 

packages and executing services. The Integration Server creates one server log per day. 

The following example shows the series of messages that are posted to server log when 

the server is started. Note that error messages are posted for services that the server 

cannot load. 

Section of server log from the start-up process 

2002-05-24 15:46:58 EDT [ISS.0025.0001C] Integration Server 6.0 

2002-05-24 15:46:58 EDT [ISS.0025.0006C] License Manager started 

2002-05-24 15:47:00 EDT [ISS.0025.0017C] Repository Manager started 

2002-05-24 15:47:03 EDT [ISS.0025.0024C] JDBC Connection Manager started 

2002-05-24 15:47:10 EDT [ISS.0025.0023C] Audit Log Manager started 

2002-05-24 15:47:10 EDT [ISS.0025.0021C] ACL Manager started 

2002-05-24 15:47:11 EDT [ISS.0025.0008C] State Manager started 

2002-05-24 15:47:14 EDT [ISS.0025.0010C] Service Manager started 

2002-05-24 15:47:14 EDT [ISS.0025.0020C] Validation Processor started 

2002-05-24 15:47:14 EDT [ISS.0025.0022C] Statistics Processor started 

2002-05-24 15:47:14 EDT [ISS.0025.0018C] Invoke Manager started 

2002-05-24 15:47:15 EDT [ISS.0025.0012C] Cache Manager started 

2002-05-24 15:47:18 EDT [ISS.0098.0026D] Transient Store DefaultStore initialized 

2002-05-24 15:47:20 EDT [ISS.0098.0026D] Transient Store TriggerStore initialized 

2002-05-24 15:47:20 EDT [ISS.0098.0021D] Trigger Dispatcher started 

2002-05-24 15:47:21 EDT [ISS.0106.0003D] Join Message Cache initialized 

2002-05-24 15:47:21 EDT [ISS.0106.0005D] Join Timeout Thread initialized 

2002-05-24 15:47:21 EDT [ISS.0106.0001D] Join Manager initialized 

2002-05-24 15:47:21 EDT [ISS.0025.0032C] Dispatcher initialized 

2002-05-24 15:47:22 EDT [ISS.0100.0001C] Web Container started 

2002-05-24 15:47:22 EDT [ISS.0025.0004C] Flow Service Manager started 

2002-05-24 15:47:22 EDT [ISS.0025.0002C] Package Manager started 

2002-05-24 15:47:22 EDT [ISS.0025.0011C] Package Replicator Manager started 

2002-05-24 15:47:22 EDT [ISS.0028.0001C] Loading packages 

2002-05-24 15:47:26 EDT [ISS.0028.0005C] Loading WmRoot package 

2002-05-24 15:48:07 EDT [ISS.0028.0005C] Loading WmPublic package 

2002-05-24 15:49:12 EDT [ISS.0028.0005C] Loading SGXOrders package 

2002-05-24 15:49:14 EDT [ISS.0028.0005C] Loading WmAdminResource package 

2002-05-24 15:49:15 EDT [ISS.0028.0005C] Loading WmAdmin package 

2002-05-24 15:49:30 EDT [ISS.0028.0005C] Loading WmPKI package 

2002-05-24 15:49:35 EDT [ISS.0028.0005C] Loading Purchasing package 

2002-05-24 15:49:36 EDT [ISS.0028.0005C] Loading Default package 


The Contents of the Server Log 


The server log file receives operational and error information from the server’s major 

subsystems. For example, the package subsystem logs information into server log when it 

loads and unloads packages; the flow manager records information in the log when it 

processes a flow service; the HTTP port records requests that it receives, and so forth. 

Be aware that the server does not log exceptions thrown by individual services. However, 

you can code your service to write information to the server log, which can be useful for 

debugging. For information about writing information to the log file, see “Writing 

Information to the Server Log” on page 310. 

Server Debug Levels 

The amount and type of information that is logged by the server is determined by the 

debug level under which the server is operating. The debug level is a value from 1 to 11 that 

you specify when you start the server. The higher the debug level, the more detail the 

server keeps in its log. 

The following example shows the startup command you would use to start the server at 

debug level 7. 

bin\server.bat –debug 7 

bin/server.sh –debug 7 

(under Windows) 

(under UNIX) 

If you do not explicitly set the debug switch when you start the server, the default value 

specified in the watt.debug.level parameter is used. webMethods ships the server with 

watt.debug.level set at 4. 

Once you start the server, the debug level is set. When the server is running, you can 

change the debug level using the Integration Server Administrator. If you do not know 

the debug level under which your webMethods Integration Server operates, see your 

webMethods Integration Server administrator. 

Important! Debug levels above 5 produce lots of detail and can quickly generate an 

extremely large log file. You should not run your server at this level except for brief 

periods when you are attempting to troubleshoot a particular issue. You may also 

optionally redirect server log messages to the console instead of a file using the –log none 

startup switch. For more information about this switch and debug levels, see “Starting the 

webMethods Integration Server” in the webMethods Integration Server Administrator’s 



Writing Information to the Server Log 


webMethods provides built-in services that allow you to write information to the server 

log at run time. These can be useful during debugging because you can use them to build 

signals that indicate whether certain segments of code were executed. You can also use 

them to record the run-time value of a specific variable. 

There are two ways to write information to the server log at run time. You can: 

� Write an arbitrary message to the log using pub.flow:debugLog. 

� Dump the contents of the entire pipeline to the log using pub.flow:tracePipeline. 

Writing an Arbitrary Message to the Log 

To write an arbitrary message to the server log, you invoke the built-in service 

pub.flow:debugLog. You can invoke pub.flow:debugLog from a flow service or a coded service 

(such as a Java service). When this service executes, it inserts a text string that you specify 

into the server log. You might use it to post progress messages at certain points in a 

service (to indicate whether certain segments of code were executed) or to record the 

value of a particular variable in the log file so you can examine it after the service executes. 

The following example shows two progress messages (highlighted) that were posted to 

the server log using pub.flow:debugLog. 

Example of messages posted to server log with pub.flow:debugLog 

2002-05-28 16:56:12 EDT [ISS.0028.0005C] Loading LogDemo package 

2002-05-28 16:56:53 EDT [ISC.0081.0001E] New LogDemo:demoService 

2002-05-28 16:57:56 EDT [ISP.0090.0003C] begin database update 

2002-05-28 16:57:56 EDT [ISP.0090.0003C] database update completed 

To use pub.flow:debugLog, take the following general steps: 

1 Invoke pub.flow:debugLog at the point where you want the service to write a message to 

the server log. 



message A String that specifies the message that you want written to server 

log. This can be a literal string that you assign to message, however, for 

debugging purposes, it is often useful to link this parameter to a 

pipeline variable whose run-time value you want to capture. 




function Optional. A String that identifies your service. The String you specify 

will appear in the second column of the message that debugLog writes 

to server log. The purpose of this label is to identify which component 

posted the message to the log. 

If you do not assign a value to function, debugLog omits the label. 

However, keep in mind that assigning a value to function will make it 

easier for you to locate your service’s message when you examine the 

log file. Although you can assign a text string of any length to 

function, only the first 6 characters appear in the log. 

level Optional. A String containing a value from 1 to 11, specifying the 

debug levels under which this message is to be posted to the log. If 

the server is running at a debug level lower than the value set in level, 

the message is not put into the log file. 




For additional information about pub.flow:debugLog, see the webMethods Integration Server 

Built-In Services Reference. 

Dumping the Pipeline to the Log 

If you do not specify level, 1 is assumed, which means that the 

message is posted to the log file regardless of which debug level the 

server is running at. For more information about debug level, see 

“Server Debug Levels” on page 309. 

Sometimes when you are debugging a service, it is useful to obtain a snapshot of the 

entire pipeline at a certain point in the flow. You can do this by invoking 

pub.flow:tracePipeline, which puts a copy of the current pipeline in server log. You may 

invoke pub.flow:tracePipeline from a flow service or a coded service (such as a Java service). 

The following example shows the start and end pipeline that was written to the server log 

with pub.flow:tracePipeline. 


Example of pipeline written to server log with pub.flow:tracePipeline 


2002-05-28 17:37:10 EDT [ISP.0090.0001C] --- START tracePipeline [5/28/02 5:37 PM] 

-- 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 filename = D:\Program 

Files\webMethods6\IntegrationServer\packages\Examples\pub\goes\catalogue.xml 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Buyer = Caroline Wielman 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Address => 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Street1 = 15788 Cedar Avenue 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 City = Apple Valley 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 State = MN 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 postalCode = 55124 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Order => 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Date = 5/25/2002 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[0] => 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 965003 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = MaxGear D LtWt D Carabiner 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Qty = 300 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Price = 8.50 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Total = 2800 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[1] => 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 896301 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = Hikes 10.5x50 Standard Rop 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Qty = 50 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Price = 175 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Total = 8750 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[2] => 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 965007 

2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = MaxGear D Quick Lock 

To use pub.flow:tracePipeline, take the following general steps: 

1 Invoke pub.flow:tracePipeline at the point where you want the service to dump a copy of 

the pipeline to the server log. 



level Optional. A String containing a value from 1 to 11, specifying the debug 

levels under which the pipeline will be posted to the log. If the server is 

running at a debug level lower than the value set in level, the pipeline is 

not written to the log file. 

If you do not specify level, 4 is assumed, which means that the pipeline 

will not be dumped to the log file unless the server is running at debug 

level 4 or higher. For more information about debug level, see “Server 

Debug Levels” on page 309. 






For additional information about pub.flow:tracePipeline, see the webMethods Integration Server 

Built-In Services Reference. 




Chapter 12. Building Coded Services 


� Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

� How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 

� Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 

� Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 

� Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 

� Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

� Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

� Writing and Invoking a Visual Basic Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 



12. Building Coded Services 

In addition to using the built-in services that webMethods provides, you can create 

customized services in a variety of program languages. This allows you to create a library 

of custom code that can be accessed and executed from a flow service or from a client 

application. 

This chapter describes how to create your own services using Java, C/C++, and Visual 

Basic. 

Important! Java is the native language for services. When you create services in other 

languages, you must wrap them to appear as a Java class to webMethods Integration 

Server. 

The IData Object 

The IData object is the universal container that services use to receive input from and 

deliver output to other programs. It contains an ordered collection of key/value pairs on 

which a service operates. An IData object can contain any number of key/values pairs 

(elements). The keys in an IData object must be Strings. The values can be any Java objects 

(including IData objects). 

Services Take IData Objects as Input and Return IData as Output 

Services take one, and only one, input variable: an IData object. For example: 

public final static void myservice (IData pipeline) 

throws ServiceException 

{ 

return; 

} 

When a service is invoked, webMethods Integration Server passes the IData object to it. 

The service extracts the actual input values it needs from the elements within the IData 

object. For example: 



{ 

IDataCursor myCursor = pipeline.getCursor(); 

if (myCursor.first( "inputValue1" )) { 

String myVariable = (String) myCursor.getValue(); 

. 

. 

} 

myCursor.destroy(); 

. 

. 

return; 

} 



A service returns output by inserting it into an IData object. Any information that is 

produced by the service and must be returned to the calling program must be written to 

the IData object. For example: 



{ 

IDataCursor myCursor = pipeline.getCursor(); 

if (myCursor.first( "inputValue1" )) { 

String myVariable = (String) myCursor.getValue(); 

. 

. 

} 

myCursor.last(); 

myCursor.insertAfter( "outputValue1", myOutputVariable ); 

myCursor.destroy(); 

return; 

} 

Getting and Setting Elements in an IData Object 

Getting data from and putting data into IData elements takes two steps. First, you must 

position the cursor at the IData element. Next, you get or set the data in that element. The 

class that you can use to position a cursor in an IData object is IDataCursor. The 

IDataCursor class contains methods for performing basic cursor operations such as 

placing the cursor at the first, last, or next element in the object. 

After you position the cursor on the element with which you want to work, you can use 

the getValue or setValue methods to read or write the value of that element, respectively. 

This class also provides methods for inserting new elements, getting key names, and 

deleting elements. 

For more information about using the cursor classes, see the data package in the 

webMethods Integration Server Java API Reference at 

webMethods6\Developer\doc\api\Java\index.html. 

Creating IData Objects 

You use the IDataFactory class to create IData objects. For example: 

static IData myIDataObject; 

static 

{ 

myObject = IDataFactory.create(); 

IDataCursor myCursor = myObject.getCursor(); 

myCursor.insertAfter("VA", new Double("0.045")); 

myCursor.insertAfter("MD", new Double("0.05")); 

myCursor.insertAfter("DE", new Double("0.0")); 

} 

For more information about using the IDataFactory class, see the data package in the 

webMethods Integration Server Java API Reference at: 



Building Services Using Java 


Since Java is the native language of services, it is the easiest language in which to build a 

service. 

webMethods Developer provides an Integrated Development Environment (IDE) that you 

can use to create, compile, and publish Java services. The IDE automatically generates an 

appropriately structured source file that you simply “fill in” using the built-in editor. 

When you save the source file, the IDE automatically compiles it and registers it on the 

server. 

Although Developer’s IDE is useful for creating small, simple services, you may want to 

use your own Java IDE to build large services. When you use your own IDE, you must 

create all of the code yourself, and manually copy and register the class file on the server. 

webMethods Integration Server provides utilities to publish services you write in your 

own IDE. For more information about creating Java services without using Developer, see 

“Building Java Services with Your Own IDE” on page 327. 

How Java Services Are Organized on the Server 

A Java service is a public static method in a Java class file on webMethods Integration 

Server. Java services follow a simple naming scheme: 

� The service name represents the Java method name. 

� The interface name represents the fully qualified Java class name. 

Since Java class names cannot contain the “.” character, services that reside in nested 

folders are implemented in a class that is scoped within a Java package. For example, a 

service named recording.accounts:createAccount is made up of a Java method called 

createAccount in a Java class called accounts within the recording package. 

All Java services that reside in the same folder are methods of the same class. 

When you build a Java service with Developer, it automatically combines your service 

into the class file associated with the folder in which you created it. However, if you build 

a Java service in your own IDE, you will need to add the class file to the server yourself. 

And, if you want that service to be recognized by Developer, you must insert special 

comment code in your source code. 


Building Java Services with Developer 


The following describes the basic stages involved in creating a Java service with 


Stage 1 

Stage 2 

Stage 3 

Specify the inputs and outputs of the service. This stage is optional, but 

recommended. During this stage, you define the service’s inputs and 

outputs (if you know these) in Developer’s IDE. For information about 

this stage, see “Generating Java Code from Service Input and Output 

Parameters” on page 325. 

Create the Java service using Developer. During this stage, you write your 

program in Developer’s IDE. For information about this stage, see 

“Creating a Java Service with Developer’s IDE” on page 323. 

Specify the service’s run-time parameters. During this stage, you assign 

parameters that configure the run-time environment for this service. For 

information about this stage, see “Setting Run-Time Options for a Java 


Before you create a Java service, you must: 

� Make sure the package in which you want to create the service already exists. If the package 

does not already exist, use Developer or the Integration Server Administrator to 

create it. For details, see “Creating a Package” on page 76. 

� Make sure the folder in which you want to create the service already exists. If the folder does 

not already exist, use Developer to create it. For details, see “Creating New Elements” 

on page 45. 

� Make sure that all Java and C services are unlocked or locked by you in the folder in which you 

want to create the new service. For details, see “Locking Java and C/C++ Services” on 

page 97. 

Important! All Java services that belong to the same folder reside in the same Java class file. 

This class has the same name as the folder. 


Developer 

automatically 

generates required 

code for you. 

Using the Developer IDE 


In the Developer IDE, you use the Java service editor and its Shared tab to create your 

source code. 

The Java Service Editor 

You use the Java service editor to build the body of your program. It is like a template you 

“fill in” with custom Java code. Standard blocks of required code appear in the shaded 

areas at the top and bottom of the tab. You cannot alter the code in these areas. 

The Java service editor is like a template for building a service 

The required code at the top of the Java service editor defines a static and final method 

with a single input parameter: an IData object. The block of required code at the bottom 

returns the pipeline to the caller. 

When you build a Java service, you type (or paste) your code in the text box in the Java 

service editor. The following example shows a service that gets two values from the 

pipeline and uses them to compute a sales tax. It puts the computed tax into the pipeline. 


Type your code 

in here. 

You use the Java service editor to write the body of your service 



The Shared Tab 


You use the Shared tab to the specify common (that is, shared) attributes of this class. This 

includes the superclass and interface declarations, required imports, and member 

variables that are shared but not exposed as services. The code on this tab is shared by all 

services in this folder. 

You use the Shared tab to specify the common attributes of the class 

The Extends field allows you to specify a super class for the implementation. You are not 

required to specify a super class. 

Note: It is useful, but not necessary, to extend the class com.wm.app.b2b.server.Service. 

This class includes static methods for various common tasks, like retrieving the current 

session ID and formatting error messages. 

The Implements field specifies the names of Java interfaces that you want to implement in 

the extended class. 

The Imports field specifies the names of additional Java packages whose classes are 

available to the current class. When you create a Java service with Developer, several Java 

packages are automatically added to the import list. 

The Source field allows you to define global variables and methods that are shared by all 

services in the current folder. This is useful for building shared data structures and 

supporting functions that are not intended to be exposed as services. For example, you 



might use the Source field to define an account table and the methods to used to access it 

for a set of services that create, get, and delete account information. 

Note: Because services are implemented as static methods, most shared code is usually 

static as well. 

Creating a Java Service with Developer’s IDE 

The following procedure describes how to create the source code for a Java service using 

Developer’s IDE. 

To create a Java service with Developer 


2 Click Java Service and click Next. 

3 In the New Java Service dialog box, next to Folder, select the folder into which you 

want to save this service. 

4 In the Name field, type a name for the service. 


6 If you know the set of inputs and outputs your program uses, specify these using the 


Note: You can use Developer to automatically generate Java code that gets and puts 

those input and output values in the pipeline. For more information about 

automatically generating Java code, see “Generating Java Code from Service Input 

and Output Parameters” on page 325. 

7 Type the code for your service at the top of the Java service editor. For information 

about Java classes provided by webMethods, see the webMethods Integration Server Java 

API Reference in webMethods6\Developer\doc\api\Java\index.html. 

8 If you want to make additional methods and/or structures available to the service, 

complete the following fields on the Shared tab. 

Use this field... To specify... 

Extends The name of the superclass (if any) of which this class is an 

extension. If you specify a superclass, type its Java class name 

(fully qualified if necessary). 


Use this field... To specify... 


Implements The names of interfaces within the superclass that this class 

implements. Take the following steps to specify each interface that 

you want to implement: 

� Click to add a new row to the list. 

� Type the name of a valid Java class name (fully qualified if 

necessary). You do not need to type the “implements” 

keyword. 

Imports The names of Java packages that this class imports. Take the 

following steps to specify each package that you want to import: 

� Click to add a new row to the list. 

� Type the name of a valid Java class name (for example, 

com.wm.util.Table) or a package import specification (for 

example, java.util.*). You do not need to type the “import” 

keyword. 

Source Data structures, methods, and other Java code that you want to 

make available to all services in this folder. 

9 When you finish specifying your code in the Java service editor and on the Shared tab, 

click on the toolbar to save and compile the service. 

10 If Developer cannot compile the service because the Integration Server to which you 

are connected cannot find a Java compiler, Developer displays an error message. Do 

the following to ensure the Integration Server can locate the Java compiler: 

a Ensure that a Java compiler is installed on the same machine as the Integration 

Server. 

b Add the location of the Java compiler to the system path of the machine where the 

Integration Server is installed. 

c Restart the Integration Server. 


Generating Java Code from Service Input and Output Parameters 


If, before you start writing your service, you know the set of inputs and outputs that it will 

use, you can declare the service’s input/output parameters first and generate Java code 

from it. This code gets the specified input values from the pipeline and assigns them to 

variables in your program. It also puts the output values into the pipeline. 

For example, if the Input/Output tab for the service defines the following variables as input 

and output: 

Input Variable Name Type 

State String 

Amount String 

Output Variable Name Type 

Tax String 

Developer will generate the following Java code for your service: 

// pipeline 

IDataCursor pipelineCursor = pipeline.getCursor(); 

StringState = IDataUtil.getString( pipelineCursor, "State" ); 

StringAmount = IDataUtil.getString( pipelineCursor, "Amount" ); 

pipelineCursor.destroy(); 

// pipeline 

IDataCursor pipelineCursor_1 = pipeline.getCursor(); 

IDataUtil.put( pipelineCursor_1, "Tax", "Tax" ); 

pipelineCursor_1.destroy(); 

When Developer generates code from the service input/output parameters, it puts the 

code on the Clipboard. From there, you can paste it into your program (at the top of the 

Java service editor or in your own IDE) and modify it as necessary. 

Note: webMethods Integration Server returns everything that your service puts into the 

pipeline, regardless of what is declared as its input/output parameters. Declaring a 

service's input and output parameters does not filter what variables the service actually 

receives or returns at run time. It simply provides a formal description of what the service 

requires as input and produces as output. 


To generate Java code from the service input/output parameters 


1 Open the Java service for which you want to generate code (if you are creating the 

Java service in your own IDE, use Developer to create a new, empty Java service that 

you will use only for the purpose of declaring a set of input/output parameters). 

2 Click the Input/Output tab and define the inputs and outputs for this service if they are 

not already specified. For more information about defining inputs and outputs for a 

service, see “To declare input and output parameters for a service” on page 133. 

3 If you want to generate code for a subset of the variables on the Input/Output tab, select 

those variables. 

4 On the Tools menu, click Generate Code. 

5 On the Code Generation dialog box, select For implementing this service and click Next. 

6 Specify the following options. 

Under this... Specify... 

Specification Whether you want to generate code for the input variables, the 

output variables, or both. 

Which fields? Whether you want to generate code for all variables in the 

Input/Output tab or just the selected variables. 

7 Click Finish. Developer generates code and places it on the Clipboard. 

8 Paste the contents of the Clipboard into your source code. 

Setting Run-Time Options for a Java Service 

When you create a Java service with Developer, you can set options to specify the 

run-time behavior of the service. These options determine whether: 

� The service runs in stateless mode. 

� The results of the service are maintained in cache. 

� An output template is applied to the service when it is invoked by a browser. 

You specify these options in the Properties panel. For information about using these 

options, see “Specifying Run-Time Parameters” on page 137 and “Assigning an Output 

Template to a Service” on page 134. 


Building Java Services with Your Own IDE 


There may be times when you want to use your own IDE instead of Developer to build a 

Java service. 

The Namespace Directory 

To successfully publish (install) a Java service that you have created with your own IDE, 

you need to understand exactly how Java services are stored on webMethods Integration 

Server. 

Each package on webMethods Integration Server has a namespace directory, called “ns.” 

For example, a package called “purch” would have the following directory structure: 

webMethods6\IntegrationServer\packages\purch\ns 

The ns directory contains information about the services in that package. An “entry” in 

the namespace directory corresponds to a service or a folder. The contents of each entry 

depend on what kind of entry it is. 

� Service entries contain information about properties of the service (for example, 

statelessness), the input and output parameters of the service (if they have been 

defined), and Java or XML source if the source is available for that service. 

� Folder entries contain information about the folder. This information is usually limited 

to Java source for the services in that folder, if available. 

For Java services, information about the service is stored in the namespace directory. 

However, the compiled code for that service (that is, the class file) is stored in the code 

subdirectory. The following shows the directory path to the class files in the purch 

package. 

webMethods6\IntegrationServer\packages\purch\code\classes\recording\ 

accounts.class 

When you use Developer to build a Java service, it automatically updates and maintains 

the folder and service information in the namespace. However, if you build a Java service 

in your own IDE, you must use a utility called jcode to compile your service and generate 

the necessary files in the namespace. 

Important! Although you may want to examine the contents of the namespace directories 

on your webMethods Integration Server, do not modify this information by hand. Only 

modify this information using the appropriate webMethods tools or utilities. 

Inappropriate changes, especially to the ns directory of the WmRoot package, can disable 

your server. 


The Source Code Directory 


Each package on the server has a source subdirectory that holds the Java source code for 

that package, if it is available. 

When you finish coding your Java service, save its source file in this directory (subject to 

the normal Java constraints based on package declarations). You must name the files and 

intermediate directories according to the name of the service you are installing. For 

example, the source file for the recording accounts services shown in Appendix E, “jcode 

tags” would have the following path: 

webMethods6\IntegrationServer\packages\purch\code\source\recording\ 

accounts.java 

Writing the Source Code for a Service 

Your service must be written as a method that takes an IData object as input. 

A Java service is a method that is public and static. It takes a single instance of 

com.wm.data.IData as input and returns output in the pipeline. The following code shows 

the basic framework for a Java service: 

public final static void myservice(IData pipeline) 


{ 

return; 

} 

Note: Services can throw ServiceException. Do not call Service.throwError. 

Additionally, 

� Your Java class must import the following Java packages. 

com.wm.data.*; 

com.wm.app.b2b.server.ServiceException; 

com.wm.app.b2b.server.Service; 

� Your Java class must be public. 

� For performance reasons, it is also recommended that you make your class final. 

Using the webMethods API 

webMethods provides classes that you can use with Java services that you build. See the 

webMethods Integration Server Java API Reference in: 

webMethods6\Developer\doc\api\Java\index.html 

for a description of these classes. 


The Basic Stages 


The following describes the basic stages involved in creating a Java service with your own 

IDE. 

Stage 1 

Stage 2 

Stage 3 

Stage 4 

Stage 5 

Commenting Code for the webMethods Integration Server 

To install your finished service on the webMethods Integration Server, you use the jcode 

utility. To use this utility successfully, you must annotate your source code with jcode tags 

(specially formatted Java comments) to “mark” the following segments of code: 

� Imports 

Create an empty Java service using webMethods Developer (optional). During 

this stage, use Developer to create an empty Java template that you can 

use a guideline for coding your own service (see “Creating a Java Service 

with Developer’s IDE” on page 323). 

Specify the input and output parameters (signature) of the service. During this 

stage, you define the service’s inputs and outputs (if you know these). 

You can use Developer to generate the input and output code that you 

can paste into your program (see “Generating Java Code from Service 

Input and Output Parameters” on page 325). 

Create the Java service using your IDE. During this stage, you write and 

compile your program in your IDE. For more information about this 

stage, see “Writing the Source Code for a Service” on page 328. 

Saving and compiling your code using jcode (optional). During this stage, you 

can make your source code available for editing by Developer by using 

the jcode utility. For information, see “Commenting Code for the 

webMethods Integration Server” on page 329. 

Publish the service to the webMethods Integration Server. During this stage, 

you register your service on the Integration Server using the jcode utility. 

For information, see “Using the jcode Utility” on page 330. 

� Shared code within the class 

� Service definitions and service inputs and outputs 



The following code fragment shows the tags used to mark the beginning and end of the 

import section. 

. 

. 

. 

// --- --import 

com.wm.data.*; 

import java.util.*; 

// --- --- 

. 

. 

. 

You use similar tags to mark the beginning and end of other components in your source 

code. For a complete example, see “jcode Example” in Appendix E, “jcode tags”. For 

additional information about the jcode utility, see the next section “Using the jcode 

Utility”. 

Using the jcode Utility 

When you finish creating and annotating your source code, you use the jcode utility to 

compile it and store its service information in the ns directory. 

Jcode operates in three basic modes: 

� Make Mode (for compiling Java source code). 

� Fragment Mode (for pulling apart source code and storing fragments and signatures in 

the namespace). 

� Composite Mode (for rebuilding the source files from fragments in the namespace). 

You must use the make and fragment modes to run your services on webMethods 

Integration Server and edit the source code from Developer. 

Important! Before you can compile a service using jcode, you must set the environment 

variable IS_DIR to point to the directory in which webMethods Integration Server is 

installed. 

Make Mode 

You use this mode to examine source files for one or more folders in a package and 

compile those that have been modified since they were last compiled. The jcode utility 

will report which files were compiled, as well as any errors that were encountered during 

the process. 

To make all the code in a package, type the following on the command line: 

jcode makeall Package 



To compile source files, the jcode utility invokes the JDK Java compiler, javac using the 

following command: 

javac –classpath pathName –d classDir fileList 

Where pathName is the classpath to use for the compile, classDir is the destination 

directory for the compiled classes, and fileList is a list of the names of source files to 

compile. 

If you do not have the JDK installed, or you want to use another compiler, you can set 

webMethods Integration Server’s watt.server.compile property to a new command line (using 

the arguments described above). For instance, to use IBM’s jikes, you would set this 

property to: 

jikes +E –nowarn –classpath pathName –d classDir fileList 

Fragment Mode 

You use this mode to update the Java code fragments and service signatures (input and 

output parameters) in the namespace based on the jcode tags in the source code file. The 

original source file is not modified, but namespace information is updated and the source 

code for the service becomes available through Developer. 

To fragment all the code in a package, type the following on the command line: 

jcode fragall Package 

To fragment only the code for a single folder (that is, a single Java source file), type the 

following on the command line: 

jcode frag Package Folder 

Composite Mode 

Composite mode is the opposite of fragment mode. You use this mode to build a source 

file based on the code fragments currently defined in the namespace. 

Important! The existing source file, if there is one, is overwritten by the source file produced 

by jcode. User locks in Developer will not prevent this, since the jcode utility operates 

independently of locking functionality. 

To construct a source file based on the current information in the namespace, type the 

following on the command line: 

jcode comp Package Folder 

Important! If your Java source code contains any non-ASCII characters, set the property 

watt.server.java.source=Unicode | UnicodeBig | UnicodeLittle. The default 

value is file.encoding. When Unicode is set, the compile command line specified in the 

property watt.server.compile.unicode is used. The default value of this property is 

“javac -encoding Unicode -classpath {0} -d {1} {2}”. 


Other jcode Commands 


Because the two-step process of making and fragmenting source code is so common, there 

are several shortcuts built in to jcode. 

The “update” mode makes and fragments only source files which have changed. To 

update (make and frag) all the folders within a package which have changed, type the 

following at the command line: 

jcode update Package 

To update (make and frag) all the code in all packages on webMethods Integration Server, 

type the following at the command line: 

jcode upall 

To force a make and frag on all packages on webMethods Integration Server, type: 

jcode hailmary 

Building Services Using C/C++ 

You can use Developer to build a set of starter files you can use to create a C/C++ service. 

These files include: 

� A Java service that calls your C program. 

� A C/C++ source-code “template” that you use to create your C program. 

� A make file you use to compile the finished program and place it on the server. 

Before you create a C/C++ service, you must: 

� Make sure you have a C compiler installed on webMethods Integration Server that you 

will use to develop and test the service. 

� Make sure the package in which you want to create the service already exists. If the package 

does not already exist, create it using webMethods Developer. For more information 

about creating a package, see “Creating a Package” on page 76. (If you do not have 

Developer or Administrator privileges, ask your server administrator to do this.) 

� Make sure the directory for this package contains a “code/libs” directory. When you compile 

your C/C++ service, the make file places the compiled service (a DLL) in this directory. 

If the package does not already have a code/libs directory, create one before you begin 

building the service. 

� Make sure the folder in which you want to create the service already exists. If the folder does 

not exist, use Developer to create it. For details, see “Creating New Elements” on 

page 45. 

� Declare the input and output parameters for your service in a specification. When Developer 

generates the starter code for your service, it creates code that extracts the specified 



input values from the pipeline and assigns them to variables in your program. It also 

inserts your service’s output variables into the pipeline. To do this, Developer must 

know the input and output requirements of your service. You supply this information 

in a specification. For information about creating a specification, see Chapter 9, 

“Creating IS Schemas, IS Document Types, and Specifications”. 

Note: If you are running the Integration Server as an NT service, you must complete 

one of the following: 

Generating Files for a C/C++ Service 

If you have satisfied the prerequisites identified above, you can use the following 

procedure to generate the files that you need to build a C/C++ service. 


2 Click C Service and click Next. 

3 In the New C Service dialog box, in the list next to Folder, select the folder into which 

you want to save this service. 

4 In the Name field, type a name for the service and click Next. 

5 Select the platform that describes the machine on which your webMethods 

Integration Server is running (Developer needs to know this in order to build the right 

make file). Click Next. 

6 Select the specification for this service. 


• Set the Windows system environment variable PATH to include 

IntegrationServer\lib 

-OR- 

• Copy the wmJNI.dll and wmJNIc.dll files located in IntegrationServer\lib 

to the IntegrationServer directory 

where IntegrationServer is the directory in which you installed the 


To generate C/C++ project files 


The Java Code for a C Service 


When you build a C/C++ service, Developer builds a Java service that calls a DLL, which 

you create by writing a C program. The Java service is the means by which your C 

program is exposed to clients (IS clients invoke this Java service, not the C program 

directly). The Java service also supplies the input/output parameters for the program, 

which makes it possible to include it in a flow service and link its inputs and output on the 

Pipeline tab. 

Developer generates all the Java code needed to successfully call your C program. You 

may add your own custom code to the C service editor or its Shared tab if you want to 

execute any special procedures before or after the C program is called, but other than that, 

this service contains everything you need. 

The C service editor contains code that calls the Java wrapper for the C program 

The Shared tab contains code that loads the library containing the C program 


The Input/Output tab declares the input/output parameters for the service 

Building the C/C++ Source Code 


Developer also generates a source code file and a make file for you. It places these files in 

the following directory: 

webMethods6\IntegrationServer\packages\packageName\code\source 

The names of the files will match the service name you specified in Developer. 

To build the C/C++ source code 

1 Locate the source code and make files. 

2 Copy the source code file to a new file (in the same directory) with the following file 

name: 

serviceNameImpl.c 

For example, if your service name is PostPO, you would copy PostPO.c to PostPOImpl.c. 

You create the program in the serviceNameImpl.c file, not the original file. This is the 

file in which the make file expects to find your source code. (This step is taken to 

maintain a copy of the original source file to which you can refer, or revert back to, 

during your development.) 

3 Edit the serviceNameImpl.c file as necessary to build your service. 

This file will contain instructive comments that will guide your development. You can 

also refer to webMethods C API for information about how to use the webMethods 

C/C++ API to make the data in your service available to other services. This file is 

located in webMethods6\Developer\doc\api\c\index.html. 



4 Edit the make file to customize it for your development environment. Set the 

following path settings: 

Set... To... 

JDKDIR To the directory that contains the Java Development Kit. 

SEVRDIR The directory in which webMethods Integration Server is 

installed (for example, c:\webMethods6\IntegrationServer). 

Important! The source code file serviceName.c contains code based on the specification 

you selected for the service. If you edit the specification, you need to regenerate the 

source code file. Developer does not update the serviceName.c file automatically. For 

more information about generating source code files for a C/C++ service, see 

“Generating Files for a C/C++ Service” on page 333. 

5 After you finish coding your service, run your make file to compile it. Following is a 

typical make command: 

make –f SalesTax.mak 

The make file compiles your program and puts the finished DLL in the code\libs 

directory in the package in which the service resides (if this directory does not exist 

when you run the make file, your program will not compile successfully). 

6 Once your program compiles successfully, restart webMethods Integration Server to 

reload the code\libs directory. This makes the service available for execution and 

allows you to test it with Developer. For details on testing, see Chapter 11, “Testing 

and Debugging Services”. 

Building Services Using COM 

There are two ways in which you can use COM objects with webMethods Integration 

Server. You can: 

� Invoke methods/properties on existing COM or DCOM objects. webMethods Integration 

Server includes built-in services for instantiating any COM or DCOM object 

registered on your system and invoking its methods and properties. This allows you 

to use existing COM APIs written in Visual Basic or Visual C++ without writing 

low-level bridging code. For details, see “Invoking Methods from Existing COM and 

DCOM Objects” on page 337. 

� Create services using COM. webMethods Integration Server includes libraries for use in 

your own Visual Basic or Visual C++ code. They allow you to create COM objects that 

perform work on webMethods data structures. These objects (compiled into ActiveX 

DLLs or EXEs) can then be registered as native services, indistinguishable from their 

Java counterparts. 


Requirements 


To use webMethods Integration Server with COM or DCOM, your webMethods 

Integration Server must be running Java Virtual Machine 1.2 or later. 

Important! If you modify Visual Basic code intended for use with webMethods Integration 

Server libraries, do not use the debug mode in the Visual Basic development environment 

to test your code. (The debugger does not maintain references to webMethods Integration 

Server libraries.) Instead, use a logging feature in your development environment to test 

the code. 

Invoking Methods from Existing COM and DCOM Objects 

You can use webMethods Integration Server to access methods in existing COM and 

DCOM libraries that do not use webMethods IData objects. For example, you may have a 

COM object that performs a validation routine on a String and returns an encrypted String 

in response. It may not be sensible or desirable to wrap this object with a service if the 

component is simple enough and/or part of an existing, unmodifiable application. In these 

cases, the dispatch services can help. 

Creating the Object 

The win32.COM.dispatch:createObject service (located in the WmWin32 package) will create an 

object given a Program ID or the Globally Unique Identifier (GUID) for that object. You 

need to provide this service with the following inputs: 

Name Description 

progid 

–OR– 

The program ID of the object that you want to invoke. 

guid The Globally Unique Identifier (GUID) of the object that you want to 

invoke. 

context The context for the object, which is INPROC (DLL), LOCAL_SERVER 

(EXE), or REMOTE_SERVER (EXE). 

server DCOM only. The TCP/IP domain name of the machine where the DCOM 

object is located. For example, doc.rubicon.com or 128.111.222.001. 

user Optional. DCOM only. The name of the user in which to launch the 

remote COM object. 

password Optional. DCOM only. The password associated with user. 

domain Optional. DCOM only. The Windows domain associated with user. 



The service will return a reference to the object called pDispatch or throw an error if the 

object cannot be created. 

Tip! The WmWin32 package is installed with the Integration Server on Microsoft Windows 

platforms but, by default, is not enabled. To view the package and access its services 

within Developer, first enable it using the Integration Server Administrator. 

Invoking the Object 

To invoke methods or properties on this object once you have created it, use 

win32.COM.dispatch:invoke. You need to supply this service with the following inputs: 


pDispatch An object reference previously obtained by the call to createObject or 

obtained in the result value of a previous call to invoke. 

dispName The name of the COM method or property that you want to invoke. 

accessType Optional. The type of operation (METHOD, GET, PUT, PUTREF) to be 

performed on dispName. If you are invoking a DCOM object, always 

set accessType to GET. Incorrect setting of this parameter will cause the 

invoke to fail. 

If you are unsure whether a dispName is a method or property, 

examine the component’s type library using OLEVIEW or a Microsoft 

development environment. 

params Optional. An object array of parameters. This is exposed in Developer 

as an array of Strings for usability (because Objects cannot be 

manipulated in Developer), but is in reality an Object array. If you need 

to pass complex or native types, you may have to create this value 

within your own service. 

If the invocation is successful, the return value is contained in “result.” If the result is an 

object variable, it can then be the target of subsequent calls to invoke by linking the result 

to pDispatch in the next invoke. 


Writing and Invoking a Visual Basic Service 


Writing services in Visual Basic is easy. To get started quickly, we suggest you examine the 

sample project file, wmVBDemo.vbp, using Visual Basic 6.0. It resides in 

WmSamples\code\source. You can find the WmSamples package in the certified samples 

area of the Knowledge Base on the Advantage Web Site. 

When you open the project, look at the Services class. It contains one method—a simple 

“HelloWorld” example. It returns “Hello” added to a name that you pass to the service. 

Note: For a complete list of all the methods contained within Values and other objects in 

the webMethods COM library, click Object Browser on the View menu in Visual Basic and 

select the webMethods library. The DLL (webMethods.dll) is registered and copied into 

your system directory during installation of Developer and webMethods Integration 

Server. 

Compiling a Visual Basic Service 

To make a Visual Basic class available to webMethods Integration Server, you must 

compile it. To compile the wmVBDemo.vbp example, open the project in Visual Basic and 

on the File menu, click Make wmVBDemo.dll. You can save the DLL in any directory. (If you 

are not sure where to put it, 

webMethods6\IntegrationServer\packages\WmWin32\code\libs will work.) 

Invoking a Visual Basic Service 

To execute a service that you have written in Visual Basic, you invoke it using one of 

webMethods Integration Server’s COM services. There are two services you can use: the 

late-binding service (win32.COM:invokeLate) and early-binding service (win32.COM:invoke). 

Invoking a VB Service Using Late Binding 

Use the following procedure to create a flow service that uses the late-binding service 

(win32.COM:invokeLate) to invoke a method from a compiled Visual Basic program. 

To invoke a VB method using late binding 

1 Open the flow service in which you want to invoke the VB method (if the service does 

not already exist, use the File�New command to create it). 

2 Click on the editor toolbar, click Browse, and then select 

win32.COM:invokeLate from the WmWin32 package. 



3 Click the Pipeline tab and use the pipeline modifier to assign values to the 

following variables in Service In: 

Set... To specify... 

$progid The name of the library and class (a standard Microsoft COM 

convention) containing the method you want to invoke. Specify 

the names using libraryName.className notation. 

The following example shows the value you would use for the 

“Hello World” example: 

Example wmVBDemo.Services 

Important! Make sure you use the exact combination of uppercase 

and lowercase letters. Library and class names are case sensitive. 

$methodName The name of the method you want to invoke. 



Example helloWorld 

$context One of the following values, specifying whether your COM object 

is a DLL or an EXE. 

Set this value... If... 

INPROC The component was compiled as an 

ActiveX DLL. This option tells the 

server to instantiate the object in the 

same process as the server. 

If you are invoking the “Hello World” 

example, select this option because the 

example was compiled as a DLL. 

LOCAL_SERVER The component was compiled as an 

ActiveX EXE. This option tells the 

server to instantiate the object as its own 

process. 

REMOTE_SERVER The object that you want to invoke is a 

DCOM object on a remote machine. 

This option tells the server to instantiate 

the object as its own process. 



4 On the Input/Output tab, declare the input and output parameters for your service. 

If you are invoking the “Hello World” example, declare a String input parameter 

name and a String output parameter message. For more information about declaring 

input and output parameters, see “To declare input and output parameters for a 

service” on page 133. 

5 On the File menu, click Save to save the flow service. 

6 On the Test menu, click Run to test the service. 

Developer prompts you for input values and then displays the results of the service in 

the Results panel. 

Invoking a VB Service Using Early Binding 

Creating a flow service that uses early binding is very much like creating one that uses 

late binding. The only difference is that, with early binding, you use win32.COM:invoke to 

invoke the Visual Basic method instead of using win32.COM:invokeLate. 

Using win32.COM:invoke provides better performance. However, it can only be used to call 

Visual Basic methods that have the following signature: 

Public Sub Sub1(inp as webMethods.Values) 

Note: If you created early-binding services with earlier versions of webMethods 

Integration Server (prior to Version 4.0), you will need to update those services and 

re-specify the input parameters for the win32.COM:invoke service as described in step 3 of the 

following procedure. 

To invoke a VB method using early binding 

1 Open the flow service in which you want to invoke the VB method (if the service does 

not already exist, use the File�New command to create it). 

2 Click on the editor toolbar, select Browse, and then select win32.COM:invoke 

from the WmWin32 package. 



3 On the Pipeline tab, use the pipeline modifier to assign values to the following 

variables in Service In: 

Set... To Specify... 

$progid The name of the library and class (a standard Microsoft COM 

convention) containing the method you want to invoke. Specify 

the names using libraryName.className notation. 



Example wmVBDemo.Services 

Important! Make sure you use the exact combination of uppercase 

and lowercase letters. Library and class names are case sensitive. 

$methodName The name of the method you want to invoke. 



Example helloWorld 

$context One of the following values, specifying whether your COM object 

is a DLL or an EXE. 

Set this value… If… 

INPROC The component was compiled as an 

ActiveX DLL. This option tells the server 

to instantiate the object in the same 

process as the server. 

If you are invoking the “Hello World” 

example, select this option because the 

example was compiled as a DLL. 

LOCAL_SERVER The component was compiled as an 

ActiveX EXE. This option tells the server 

to instantiate the object as its own process. 

REMOTE_SERVER The object that you want to invoke is a 

DCOM object on a remote machine. This 

option tells the server to instantiate the 

object as its own process. 



4 On the Input/Output tab, declare the input and output parameters for your service. 

If you are invoking the “Hello World” example, declare a String input parameter 

name and a String output parameter message. For more information about declaring 

input and output parameters, see “To declare input and output parameters for a 

service” on page 133. 

5 On the File menu, click Save to save the flow service. 

6 On the Test menu, click Run to test the service. 

Developer prompts you for input values, executes the service, and then displays the 

results of the service in the Results panel. 




Chapter 13. Creating Client Code 


� Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

� Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 

� Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

� Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 

� Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 



13. Creating Client Code 

webMethods Developer enables you to automatically generate client code in a variety of 

languages and for several environments. Client code is application code that invokes a 

service on a webMethods Integration Server. It typically performs the following basic 

tasks: 

� Prompts the user for input values (if your service takes input) 

� Places the inputs into an input document (if your service takes input) 

� Opens a session on webMethods Integration Server 

� Invokes a service 

Building a Java Client 

� Receives output from the service 

� Closes a session on webMethods Integration Server 

� Displays the output to the user 

The client code that Developer generates can serve as a good starting point for your own 

development. 

You can use Developer to generate Java client code that invokes a service. 

Assumptions 

� webMethods Integration Server is running. 

� A fully functional JDK is installed. If you are using the JVM that was installed with the 

Integration Server, no further action is needed. If you are using a different JVM, do the 

following to obtain the files the Integration Server needs to support signed libraries: 


If your run-time 

JDK is... Do the following... 

JDK 1.2.* or 

JDK 1.3.* 


Ensure that the Sun JCE 1.2.2 is installed as part of your JVM 

installation. 

� If you are running the Sun JVM, look for the files jce1_2_2.jar, 

local_policy.jar, sunjce_provider.jar, and 

US_export_policy.jar. 

� If you are running the IBM JVM, look for the files 

IBMJCEfw.jar, IBMJCEProvider.jar, local_policy.jar, and 

US_export_policy.jar. 

If these files are not installed, download the Sun JCE 1.2.2 from 

http://java.sun.com/products/jce/index-122.html. 

JDK 1.4.* Ensure that the unlimited strength jurisdiction policy files 

(local_policy.jar and US_export_policy.jar) are installed as part of 

your JVM installation. 

If these files are not installed, download them as follows: 

� If you are running the Sun JDK 1.4.*, download the files from 

http://java.sun.com/j2se/1.4.1/download.html/. 

� If you are running the IBM JDK 1.4.*, download the files from 

http://www-106.ibm.com/developerworks/java/jdk/security/. 

JDK 1.5.* Ensure that the unlimited strength jurisdiction policy files 

(local_policy.jar and US_export_policy.jar) are installed as part of 

your JVM installation. 

If these files are not installed, download them as follows: 

� If you are running the Sun JDK 1.5.*, download the files from 

http://java.sun.com/javase/downloads/index.jsp. 

If you are running the IBM JDK 1.5.*, download the files from 

http://www-106.ibm.com/developerworks/java/jdk/security/. 

� You are using one of the cryptographic service providers (CSPs) that webMethods 

provides (Sun, IBM, Entrust, or IAIK). If you are using a different provider, the 

libraries supplied by that provider must be digitally signed. 

� Your classpath consists of at least the following: 

webMethods6\Developer\lib\client.jar 

Note: The client.jar file refers to the files in webMethods6\Developer\lib\entrust. 

Therefore, the \entrust directory must remain in the same relative path as client.jar. 


Third-Party Libraries 


The following table describes the third-party libraries that webMethods includes in 

webMethods6\Developer\lib\client.jar and in webMethods6\Developer\lib\entrust. 

Libraries Source 

webMethods6\Developer\lib\entrust 

Entrust Authority Security Toolkit for 

Java 7.2 

webMethods6\Developer\lib\client.jar 

Limitations 

Entrust Inc. 

http://www.entrust.com 

Jakarta ORO Source Version 2.0.5 Apache Software Foundation 

JavaBeans Activation Framework 1.01 

Java API for XML Parsing (JAXP) 1.2.2 

International Components for Unicode for 

Java Download ICU4J version 2.6 

http://jakarta.apache.org/oro/index.html 

� When Developer generates client code, it ignores input or output variables that are of 

type Object or Object list. Client code is not generated for these variables. 

� When Developer generates client code, Developer replaces any space in a variable 

name with an underscore. 

� The client code that Developer generates does not support multiple input or output 

variables with the same name. 

If you want to override these limitations, you will need to modify the client code that 

Developer generates. 


Sun 

http://java.sun.com 

IBM 

http://oss.software.ibm.com/icu4j/downl 

oad/2.6/ 

Xerces Java Parser 2.6.2 Apache Software Foundation 

http://xml.apche.org/xerces2-j/

Procedure 


Use the following procedure to generate Java client code that invokes a service: 

To generate Java client code that invokes a service 

1 Open the service for which you want to generate client code. 


3 In the Code Generation dialog box, select For calling this service from a client, and then 

click Next. 

4 In the Language field, select Java, and then click Next. 

5 Specify the directory where you want Developer to place the generated client code. 

Either select an existing directory or type the path for a new directory. If you type the 

path for a new directory, Developer creates the directory. 


Developer generates the file that contains the Java client code (ServiceName.java) and 

a Readme.txt file. The Java client code is written to the hard disk in ISO8859_1, the 

character set in which the file is encoded. 

Modify the generated client code to meet your site’s needs. You can update the client 

code to invoke built-in services and to use the provided Java API. For information 

about the built-in services that are available, see the webMethods Integration Server 

Built-In Services Reference. Documentation for the Java API can be found at 


To complete your client application, refer to the Readme.txt file located in the same 

directory as your client code. 

Files that Are Generated 

This section describes the files that Developer generates for a Java client application. 

File Name Description 

Readme.txt A file that contains information and instructions for the Java client 

code. Refer to this file for information about compiling and 

running the Java client application. 

ServiceName.java An example file, encoded in ISO8859_1, that contains the 

application code for the Java client. The application code includes 

a rudimentary user interface that uses the classes in the FolderName 

directory. It is not intended for use “as is” in custom applications. 


Building a C/C++ Client 

You can use Developer to generate C/C++ client code that invokes a service. 

Assumptions 



� A platform that has the C/C++ compiler (for example, GCC) is installed. webMethods 

generates code for the following platforms: Windows, Solaris, HP-UX, Linux, AIX. 

� The client.jar file is in the classpath for Developer. The client.jar file is a webMethods 

file that is located in the webMethods6\Developer\lib directory. 

� The Make facility is installed. 

� JDK 1.1.x is installed (if you intend to use the C libraries provided with Integration 

Server and Developer). 

Important! The provided C libraries are built using JDK 1.1.7. If you want to use a different 

version of the JDK to compile C/C++ services, you need to rebuild the C/C++ libraries with 

that JDK and then replace the old library files with the rebuilt ones. For more information 

about rebuilding the C libraries, see the README installed with the C/C++ SDK. 

To rebuild the C libraries, you need use the C/C++ SDK. The C/C++ SDK is not installed by 

default. To install the C/C++ SDK, select it from the list of installable components during 

installation. 

Limitations 








Procedure 


Use the following procedure to have Developer generate C/C++ client code that invokes a 

service: 

To generate C/C++ client code that invokes a service 



3 In the Code Generation dialog box, select For calling this service from a client; then click 

Next. 

4 In the Language field, select the C/C++ platform for which you are creating client code. 

Click Next. 

5 Identify the directory where you want Developer to place the generated client code. 




Developer generates the file that contains the C client code (ServiceName.c), a file that 

contains compiling settings (ServiceName.mak), and a CReadme.txt file. 

Modify the generated client code to meet your site’s needs. You can update the client 

code to invoke built-in services and to use the webMethods provided C API. For 

information about the built-in services that are available, see the webMethods 

Integration Server Built-In Services Reference. For documentation about the C API, see 

webMethods6\Developer\doc\api\C\index.html. 

To complete your client application, refer to the CReadme.txt file located in the same 

directory as your client code. 


This section describes the files that Developer generates for a C/C++ client application. 


CReadme.txt A file that contains information and instructions for the C client 

code. Refer to this file for information about compiling, running, 

and deploying your C/C++ client application. 

ServiceName.mak A file that contains compiling settings for the C/C++ client. Be sure 

to update this file with the correct settings for your environment. 

ServiceName.c An example file that contains the C/C++ client code. It is not 

intended for use “as is” in custom applications. 


Building a Visual Basic Client 


You can use Developer to generate Visual Basic client code that invokes a service. 

Developer creates files that contain the layout and the code for your application. 

Assumptions 


� Visual Basic Version 6 is installed. 

� webMethods 6 Type Library is installed. 

Note: The webMethods 6 Type Library is a COM object that Visual Basic uses to interact 

with webMethods Integration Server. The webMethods 6 Type Library is automatically 

installed when you install Developer. 

Environment Setup 

Your system PATH environment variable must include the following directory: 

webMethods6\jvm\win142\jre\bin\client 

Limitations 

� The client code that Developer generates supports only input values and output 

values of type String, String list, and String table. 








Procedure 


Use the following procedure to have Developer generate Visual Basic client code that 

invokes a service. 

To generate Visual Basic client code that invokes a service 



3 In the Code Generation dialog box, select For calling this service from a client, and click 

Next. 

4 In the Language field, select Visual Basic 5/6, and click Next. 





Developer generates several files, including the serviceNameReadMe.txt file. This file 

contains detailed information about all the generated files. Refer to it to complete your 

client application and for information about deploying your client application. 


This section describes the files that Developer generates for a Visual Basic client 

application. 

General Files 


ServiceName.vbp The Visual Basic project file. 

ServiceNameReadme.txt The file that contains information and instructions for the 

Visual Basic client code. Refer to this file for information 

about deploying your Visual Basic client application. 


Files for the User Interface 


Files Containing the Code that Invokes the Service 


frmArrayInput.frm Contains layout and code that is used if any of the input 

values for the service are of type String list. 

frmOutput.frm Contains layout and code that is used when the service 

returns output. It also contains the Setup, Invoke, and Exit 

buttons. 

frmSetup.frm Contains layout and code that prompts for the server 

properties for the webMethods Integration Server on which 

the service to execute resides. 

frmStringInput.frm Contains layout and code that is used if any of the input 

values for the service are of type String. 

frmTableInput.frm Contains layout and code that is used if any of the input 

values for the service are of type String table. 

wmSampleLib.bas Contains code that is specific to the sample template that 



ServiceName.bas An example file that illustrates how to use the service class 

in an application. This module is dependent on objects in the 

project template that webMethods provides. It is not 


ServiceName.cls The service object. You include this object in your own 

project. 

File Containing the Code that Interacts with webMethods Integration Server 


wmVBConnection.bas Code used as a layer of abstraction to interact with 



Building an Excel Client 


You can use Developer to generate client code that executes a service from a MS Excel 

spreadsheet. 

Assumptions 


� Excel 97 or Excel 2000 is installed. 

� webMethods 6 Type Library is installed. 

Note: The webMethods 6 Type Library is a COM object that Visual Basic uses to interact 

with webMethods Integration Server. The webMethods 6 Type Library is automatically 

installed when you install Developer. 

Limitations 

� The client code that Developer generates only supports input values of type String 

and output values of type String, String list, and String table. 







Procedure 

Use the following procedure to have Developer generate Excel client code that invokes a 

service. 

To generate Excel client code that invokes a service 



3 In the Code Generation dialog box, select For calling this service from a client, and click 

Next. 

4 In the Language field, select Excel 97/2000, and click Next. 







Developer generates several files, including the serviceNameReadMe.txt file. This file 

contains detailed information about all generated files. 

7 Copy the wmXLTemplate.xls file, which webMethods provides, to the directory that 

contains the client code that Developer generated. The wmXLTemplate.xls file is 

located in the webMethods6\Developer\support\Excel directory. 

8 Open the wmXLTemplate.xls file. When prompted to indicate whether you want to 

enable macros, select Enable Macros. 

9 Follow the instructions in the wmXLTemplate.xls file to complete your client 

application. See the ServiceNameReadMe.txt file for information about deploying your 

client application. 


This section describes the files that Developer generates for an Excel client application. 


ServiceNameReadMe.txt A file that contains information and instructions for the 

Visual Basic client code. Refer to this file for information 

about deploying your Visual Basic client application. 

ServiceName.bas An example file that illustrates how to use the service class 

in a spreadsheet. This module is dependent on objects in the 

project template that webMethods provides. It is not 


ServiceName.cls The service object. You include this object into your own 

project. 

Building a Browser-Based Client 

You can invoke a service with a URL. This means that you can invoke a service by entering 

the URL into your Web browser or by embedding the URL in Web pages. 

To build a browser-based client, create one or more Web pages that invoke URLs for one 

or more services. When webMethods Integration Server receives the first URL from a Web 

browser, it creates a session for the client on webMethods Integration Server. The session 

information is stored in a cookie in the browser. As the user of the browser-based 

application clicks on links to URLs that invoke services, webMethods Integration Server 



uses the cookies to find session information for the client. webMethods Integration Server 

keeps the session information for the client until the session expires. Sessions expire based 

on the configured session time-out value. For more information about setting the session 

time-out limit, refer to the webMethods Integration Server Administrator’s Guide. 

Note: You cannot use Developer to generate browser-based clients. 

Assumptions 


� The input values for the services you want to invoke are determined. You will need to 

include the input values in the URL that you use to invoke a service. 

Limitations 

When you test a service using the Run in Browser command, only input values of the type 

String and String list will be passed to the service. Input values of the type document, 

document list, Object, and Object list will not be displayed when the Web page is served. 

Invoking Services with a URL 

First, build your Web pages using any tool you choose. To invoke the URL, use either the 

HTTP GET or the POST method. In either case, use a URL similar to the following: 

Item Description 

1 

2 

3 

1 2 3 4 5 

http://IS_server:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1 

Identifies the webMethods Integration Server on which the service you want 

to invoke resides. 

Specifies the required keyword “invoke”, which tells webMethods 

Integration Server that the URL identifies a service that is to be invoked. 

Identifies the folder in which the service to invoke resides. Separate 

subfolders with periods. This field is case sensitive. Be sure to use the same 

combination of upper and lower case letters as specified in the folder name 

on webMethods Integration Server. 


Using the HTTP GET Method 


Item Description 

4 Identifies the service that you want to invoke. This field is case sensitive. Be 

sure to use the same combination of upper and lower case letters as specified 

in the service name on webMethods Integration Server. 

5 

Specifies the input values for the service. Specify a question mark (?) before 

the input values. The question mark signals the beginning of input values. 

Each input value is represented as variable=value. The variable portion is case 

sensitive. Be sure to use the same combination of upper and lower case 

letters as specified in your service. If your service requires more than one 

input value, separate each variable=value with an ampersand (&). 

Note: Only specify this part of the URL when using the HTTP GET method. 

Note: If you are serving the Web pages that invoke services from a webMethods 

Integration Server, you can use a relative URL to invoke the service. By doing so, you can 

serve the exact Web page from several servers without having to update the URLs. 

To use the GET method, embed a URL that includes all the input values for the service in 

the query string portion of the URL. When the server receives the URL, it translates the 

input values into an IData object. For more information about how the server creates the 

IData object that it sends to the service, refer to “Input to the Service” on page 359. 

Using the HTTP POST Method 

To use the POST method, create an HTML form in your Web page. Create fields in the 

HTML form in which a user will supply the input information. The values you specify for 

the NAME attributes of the HTML form fields should match the names of input values 

that the service expects. Be sure to use the exact combination of upper and lower case 

letters as specified in your service. For example, if your service requires the input values 

sku and quantity, you might create an HTML form with the following fields: 

 

A1 

B2 

C3 

 

 



Specify the URL for the service in the ACTION attribute and “POST” in the METHOD 

attribute. For example: 

 

After the user fills in the form and submits it, the Web browser creates a document that 

contains the information the user supplied in the HTML form (performs an HTTP POST). 

The browser invokes the URL identified in the ACTION attribute, which invokes the 

service on webMethods Integration Server, and the browser posts the document that 

contains the user’s input information to webMethods Integration Server. For more 

information about how the server creates the IData object that it sends to the service, see 

“Input to the Service” on page 359. 

Input to the Service 

Regardless of whether webMethods Integration Server receives a URL that uses the HTTP 

GET or POST method, it creates an IData object from the input information. It then passes 

the IData object to the specified service. This becomes the pipeline upon which the service 

operates. 

To create the pipeline object, webMethods Integration Server creates two key/value pairs 

for each input value: one of type String and one of type String list. For example, if the 

input values contain the variable sku with value A1 and quantity with value 1, the service is 

passed the following IData object: 

Key Value Data Type 

sku A1 String 

skuList A1 String list 

quantity 1 String 

quantityList 1 String list 

Note: Avoid using input variable names that end in “List.” Although the Integration Server 

will accept variable names ending in “List,” the resulting IData may not be structured in 

the way you need. For example, if you were to pass in a variable called “skuList,” the 

resulting IData will contain a String called “skuList” and a String list called “skuListList.” 

Moreover, if you were to pass in variables named “sku” and “skuList,” subsequent “sku” 

and “skuList” variables in the query string may not be placed in the IData fields as 

expected. 

If you must use “List” at the end of your variable name, consider using “list” (lowercase) 

or appending one or more characters at the end of the name (for example, abcListXX). 



When the server receives multiple input values that are associated with the same variable 

name, the String variable in the IData object contains only the value of the first variable; 

the String list variable contains all values. For example, the following shows a URL that 

contains two values for the variable year and the resulting IData object that the server 

creates: 

/invoke/sample.webPageDemo/checkYears?year=1998&year=1999 


year 1998 String 

yearList 1998 

1999 

String list 

Similarly, if the HTML form contains two fields with the same name and a user supplies 

values for more than one, the String variable in the IData object contains only the value of 

the first variable; the String list variable contains all values. For example, the following 

shows sample HTML code that renders check boxes: 

Blue 

Green 

Red 

If the browser user selects all check boxes, the document that is posted to webMethods 

Integration Server will contain three values for the variable named Color. The following 

shows the IData object that the server passes to the service: 


Color blue String 

ColorList blue 

green 

red 

String list 

Output from the Service 

By default, webMethods Integration Server displays the output from a service in a HTML 

Web page, using a table to render the output values. However, you can format the output 

using output templates. You can use an output template that formats the output from one 

service and includes a URL that invokes another service. For more information about 

output templates, see “Assigning an Output Template to a Service” on page 134. 


Chapter 14. Subscribing to Events 

� The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 

� Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 

� Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 

� Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 

� Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 

� Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 

� Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 

� Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 

� Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

� Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 

� Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

� Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 


The Event Manager 

14. Subscribing to Events 

The Event Manager monitors the server for events and invokes event handlers when those 

events occur. An event is a specific action that the Event Manager recognizes and an event 

handler can react to. An event handler is a service that you write to perform some action 

when a particular event occurs. 

Currently, the Event Manager recognizes the following types of events: 

� Alarm events occur when the Integration Server throws an exception regarding the 

status or health of the server. The server generates alarm events when a user cannot 

log on to the server, a port cannot be started, a user is denied access to a port, an error 

occurs in Cluster Manager, or a service cannot execute because of errors. Subscribe to 

alarm events to invoke event handlers that perform specific actions such as notifying 

administrators about port access exceptions and service failures, or sending 

information to a console when a port cannot be started. 

� Audit events occur when a service generates audit data. Subscribe to audit events to 

invoke specific actions when a particular service or class of service executes. 

� Exception events occur every time a service throws an exception. Subscribe to exception 

events to invoke specific event handlers when a particular service or class of service 

fails. 

� Guaranteed Delivery events occur when a client uses guaranteed delivery to invoke a 

service on a Integration Server and when the server returns the service results to the 

requesting client. There are two types of guaranteed delivery events: GD Start and GD 

End. Subscribe to GD Start and GD End events to invoke event handlers that perform 

actions such as logging guaranteed delivery transactions to a file or sending 

notification. 

� Port Status events occur each time the Integration Server updates the server statistics. 

The port status event provides information about the status of all the ports configured 

on Integration Server. Subscribe to port status events to invoke event handlers that 

perform actions such as sending port status data to a network monitoring system or 

writing port status data to a log file. 

� Replication events occur when the pub.replicator:generateReplicationEvent service executes. 

Subscribe to replication events to invoke event handlers that perform actions such as 

notifying package subscribers when a package is published and maintaining a log of 

pulled or distributed packages. 

� Session events occur when a client starts or ends a session on the Integration Server or 

when the Integration Server terminates an inactive session. There are three types of 

session events: session start, session end, and session expire. Subscribe to session 

events to invoke event handlers that perform actions such as maintaining your own 

log files. 



� Stat events occur each time the Integration Server updates the statistics log (stats.log). 

Subscribe to stat events to invoke event handlers that perform actions such as 

maintaining your own log file or sending server statistics to a network monitoring 

system. 

� Transaction events occur when an Integration Server begins and finishes processing a 

guaranteed delivery transaction. There are two types of transaction events: Tx Start 

and Tx End. Subscribe to transaction events to invoke event handlers that perform 

specific actions (such as sending notification or logging information) when a 

particular guaranteed delivery transaction begins or finishes processing. 

What Are Event Handlers? 

An event handler is a service that you write to perform some action when a particular event 

occurs. (An event handler can be any type of service, such as a flow service or a Java 

service.) Event handlers subscribe to the events that they want to be notified of. For 

example, if you wanted an event handler to execute when a particular service throws an 

exception, you subscribe the event handler to the exception event for that service. 

What Happens When an Event Occurs? 

When an event occurs, the Event Manager automatically invokes all event handlers that 

subscribe to the event. The event handlers receive an input object containing run-time 

information. The exact content of this input object varies depending on the type of event 

that occurred and, for audit events, the run-time properties set on both Integration Server 

and the service that generated the event. 

Once an event handler is invoked, its execution is completely asynchronous of the event 

that invoked it. If the execution of a service invokes an event handler (as with audit and 

exception events), the execution path of the invoking service is not blocked or altered in 

any way (in fact, it is never even aware that it invoked an event handler). 

Other points to keep in mind about events and event handlers: 

� An event can have more than one subscriber, which means that a single event might 

invoke several event handlers. 

� If an event invokes more than one event handler, all the event handlers execute 

simultaneously. They do not execute serially and they are not invoked in any 

particular order. (If you have a series of actions that must execute in a specific 

sequence, you should encapsulate the entire sequence within a single event handler.) 

� An event handler can subscribe to more than one event. 

� When event handlers run, they do not generate audit events. 

� If an event handler throws an exception, it generates an exception event. This is true 

for all event handlers but exception event handlers. When an exception event handler 

throws an exception, it does not generate an exception event. 


Managing Event Subscriptions 

To subscribe to an event, 

specify the type of event 

that you want to react to... 

...a filter to select the 

specific events you want 

to react to... 

...and the name of the 

event handler that is to 

be executed when this 

event occurs. 


You can use the Event Manager in Developer to manage all of your event subscriptions. 

The Event Manager can perform the following tasks: 

� Subscribe event handlers to events. 

� View or edit event subscriptions. 

� Suspend event subscriptions. 

� Delete event subscriptions. 

The following sections contain more information about each of these tasks. 

Note: You can also use built-in services to add, modify, and delete event subscriptions. 

These services are located in the pub.event folder. For more information about built-in 

services, see the webMethods Integration Server Built-In Services Reference. 

Subscribing to an Event 

You can use the Event Manager in Developer to subscribe to an event on the current 

server. This action registers the event handler with the Event Manager and specifies which 

events will invoke it. To access the Event Manager, use the Tools�Event Manager command. 

Use the Event Manager in Developer to subscribe to events 

Use the following procedure to subscribe to an event on the current server. To perform 

this procedure, you must have already: 

� Identified the event type you want to subscribe to 

� Identified the service or services that generate an event you want to subscribe to (if 

you want to subscribe to an audit event, exception event, or GD Start event) 

� Written the event handler that will execute when the identified event occurs 


To subscribe to an event on the current server 

1 On the Tools menu, click Event Manager. 


2 In the Event Manager dialog box, in the View event subscribers for list, select the event 

type to which you want to subscribe. 

3 Click to add a new subscriber. 

4 In the Enter Input Values dialog box, complete the following fields: 


Service The fully qualified name of the event handler that will subscribe to the 

event (that is, the service that will execute when the event occurs). You 

can either type the name in the Service field or click to locate and 

select the service from a list. 

Example: sgxorders.Authorization:LogAuthTrans 

Filter A pattern string to further limit the events this event handler 

subscribes to. Filters vary depending on the event type you are 

subscribing to. 

For example, if you are subscribing to an audit or exception event, 

create a filter to specify the names of services whose events this event 

handler subscribes to (that is, the services that, when executed, will 

invoke the event handler specified in Service). 

You can use the * character as a wildcard (this is the only wildcard 

character recognized by this pattern string). The pattern string is case 

sensitive. 

For more information about creating event filters, see “Creating Event 

Filters” on page 366. 

Comment An optional descriptive comment about this subscription. 

Enabled Whether the subscription is active or inactive. Set to true to activate the 

subscription. Set to false to deactivate the subscription. (This allows 

you to temporarily suspend a subscription without deleting it.) 

5 Click OK. Subscriptions take effect immediately. 

Note: The Integration Server saves information for event types and event subscriptions in 

the eventcfg.bin file. This file is generated the first time you start the Integration Server 

and is located in the following directory: webMethods6\IntegrationServer\config. Copy 

this file from one Integration Server to another to duplicate event subscriptions across 

servers. 


Creating Event Filters 


Event filters allow you to be very selective about which events you subscribe to. Event 

filters limit the events for an event type that invoke an event handler. By using event 

filters, you can subscribe an event handler to only those events generated by a particular 

service, package, user, or port. For example, you might want an event handler to be 

invoked only when a specific service generates an audit event. Or, you might want an 

event handler to be invoked only when a specific user logs on to the Integration Server. 

The following table identifies the information that you can filter on for each event type. 

Notice that you cannot create a filter for some event types. For these event types, every 

generated event invokes the event handlers subscribed to it. 

Important! The asterisk (*) is the only wildcard character allowed in an event filter. All other 

characters in the pattern string are treated as literals. Pattern strings are case sensitive. 

For this event type... You create a filter for... 

Alarm Event The message generated by the alarm event. Create a filter that 

specifies some of the text of the message. The event handler with 

this filter will process all alarm events containing the specified 

text. 

The following filter specifies that any alarm events that generate 

a message containing the word “port” will invoke the event 

handler: 

*port* 

Audit Event The fully qualified name of the service that generates the audit 

event. Create a filter to specify the services whose audit events 

you want to invoke the event handler. 

The following filter specifies that the service 

sgxorders.Authorization:creditAuth will invoke the event handler: 

sgxorders.Authorization:creditAuth 

Exception Event The fully qualified name of the service that generates the 

exception event. Create a filter to specify the services whose 

exception events you want to invoke the event handler. 

The following filter specifies that all services that start with the 

word “credit” and belong to any folder will invoke the event 

handler: 

*:credit* 



GD End Event N/A 


The filter for all GD End events is the following: 

* 

GD Start Event The fully qualified name of the service that is being invoked 

using guaranteed delivery. Create a filter to specify the services 

that, when invoked using guaranteed delivery, will invoke the 

event handler. 

Port Status Event N/A 

The following pattern string specifies that all services that start 

with the word “sendPO” and belong to any folder will invoke the 

event handler: 

*:sendPO* 

The filter for all port status events is the following: 

* 

Replication Event The name of the package being replicated. Create a filter to 

specify the packages that, when replicated, will invoke the event 

handler. 

Session End Event N/A 

The following filter specifies that a replication event involving 

the package named “AcmePartnerPkg” will invoke the event 

handler: 

AcmePartnerPkg 

The filter for all session end events is the following: 

* 

Session Expire Event N/A 

The filter for all session expire events is the following: 

* 

Session Start Event The user name for the user starting the session on the Integration 

Server or the groups to which the user belongs. Create a filter to 

specify which users or which user groups invoke an event 

handler when they start a session on the server. 

The following filter specifies that a session start event generated 

by a user in the “Administrators” group will invoke the event 

handler. 

*Administrators* 



Stat Event N/A 

The filter for all stat events is the following: 

* 

Tx End Event N/A 

The filter for all Tx End events is the following: 

* 

Tx Start Event N/A 

Creating Event Filters for Services 

The filter for all Tx Start events is the following: 

* 


When you create a filter for a service name, you can be very selective about which 

service’s events you subscribe to. You can use regular expressions to create event filters for 

service names. The following examples show ways you can use regular expressions as 

event filters to specify an event that a particular service generates. 

This filter... Will select events generated by... 

sgxorders.Auth:creditAuth The service sgxorders.Auth:creditAuth. 

sgxorders.Auth:credit* All services in the sgxorders.Auth folder, starting with 

the characters “credit.” 

sgxorders.Auth:* All services in the sgxorders.Auth folder. 

sgxorders.* All services in the sgxorders folder and its subfolders. 

*.Auth*:credit* All services starting with the characters “credit” that 

reside in any subfolder whose name starts the 

characters “Auth.” 

*:credit* All services starting with the characters “credit” in 

any folder. 

* All services. 


Viewing and Editing Event Subscriptions 

To view or edit an event subscription on the current server 



2 In the View event subscribers for list, select the event type for which you want to view 

subscriptions. 

3 Click the subscription you want to edit, and then click . 

4 Modify the fields in the Enter Input Values dialog box as needed and then click OK. 

5 Repeat steps 2–4 for each subscription you want to view or edit. 

6 Click OK when you finish viewing or editing event subscriptions. Your changes take 

effect immediately. 

Suspending Event Subscriptions 

You can suspend an event subscription. By suspending an event subscription, you 

temporarily stop the execution of the event handler without deleting or removing the 

event handler. While the event subscription is suspended, the Event Manager does not 

invoke the associated event handler when the server generates the event to which it is 

subscribed. You can resume an event subscription at any time. 

To suspend an event subscription 



type for which you want to suspend a subscription. 

3 Click the subscription you want to edit, and then click . 

4 In the Enter Input Values dialog box, in the Enabled list, select false. 

5 Repeat steps 2–4 for each event subscription you want to suspend. 

6 Click OK when you finish suspending event subscriptions. Your changes take effect 

immediately. 


Deleting an Event Subscription 

To delete an event subscription 




type for which you want to delete a subscription. 

3 Click the subscription you want to delete, and then click . 

4 Repeat steps 2 and 3 for each subscription you want to delete. 

5 Click OK when you finish deleting events. Your changes take effect immediately. 

Building an Event Handler 

Building an event handler involves the following basic stages: 

Stage 1 

Stage 2 

Stage 3 

Stage 4 

Stage 5 

Creating an empty service. During this stage, you create the empty service that 

you want to use as an event handler. 

Declaring the input and output. During this stage, you declare the input and 

output parameters for the event handler by selecting the specification or IS 

document type for the event type in pub.event. The specification and IS 

document type indicate the run-time data that will be contained in the IData 

object passed to the event handler. 

Inserting logic, code, or services. During this stage, you insert the logic, code, 

or services to perform the action you want the event handler to take when 

the event occurs. If you are building a flow service, make sure to link data 

between services and the pipeline. 

Testing and debugging the service. During this stage, you use the testing and 

debugging tools available in Developer to make sure the event handler 

works properly. 

Subscribing to the event. During this stage, you use the Event Manager to 

subscribe the event handler to the event. This action registers the event 

handler with the Event Manager and specifies which events will invoke it. 

You can create filters to be more selective about which events you subscribe 

to. 


Sample Event Handler 


Following are instructions for building an event handler named processLogon. The 

processLogon event handler sends a notification to a specified email address (such as the 

Server Administrator) when anyone in the Administrators group logs in to the Integration 

Server. 

Stage 1 To create the event handler 

� Create an empty flow service and name it processLogon. 

Stage 2 To assign input and output parameters to the event handler 

1 On the Input/Output tab, next to the Specification Reference field, click . 

2 In the Select dialog box, navigate to and select the pub.event:sessionStart specification. 

3 Click OK. 

Stage 3 To insert services into the event handler 

1 On the editor toolbar, click and select Browse. 

2 In the Browse dialog box, navigate to and select the pub.client:smtp service. Click OK. 

3 On the Pipeline tab, use the Set Value modifier to assign values to the following 

variables in Service In: 

For this field… Specify… 

to The email address for the person to send event notification to. 

subject 

%userid% logged in 

The subject of the email message will contain the user ID of the 

person who logged on to the Integration Server as a member of the 

Administrators group. 

mailhost The network name of your mailhost (for example, 

mail@mycompany.com). 

body 

Administrators user %userid% logged into session 

%sessionName% with session ID %ssnid% 

The body of the email message will contain the user name, session 

name, and session ID for the person who logged on to the 

Integration Server as an Administrator. 

4 On the File menu, click Save to save the service. 


Stage 4 To test and debug the event handler 


� Use the testing and debugging tools in Developer (such as Test�Run) to test and 

debug the service. For more information about these tools, see Chapter 11, “Testing 

and Debugging Services”. 

Stage 5 To subscribe the event handler to the event 


2 In the Event Manager dialog box, in the View event subscribers for list, select Session Start 

Event. 

3 Click to add a new event subscription. 

4 In the Enter Input Values dialog box, complete the following fields: 

In this field… Do this… 

5 Click OK. Subscriptions take effect immediately. 

Working with Alarm Events 

Service Click and use the Select dialog box to navigate to and select the 

Filter 

processLogon service. 

Type: *Administrators* 

This pattern string specifies that the processLogon event handler will 

execute only when a user belonging to a user group containing the 

string “Administrators” logs on to the server. 

For more information, see “Building Handlers for Session Start 

Events” on page 383. 

Comment Specify a descriptive comment about this subscription. 

Enabled Select true to activate the subscription. 

An alarm event occurs when the Integration Server generates a message related to the 

status of the server. An alarm event can be generated for the following reasons: 

� A client experiences a logon failure or is denied access to the Integration Server. A 

client cannot log on because of “invalid credentials.” 

� Errors occur in the Cluster Manager. The inability to add a port to a cluster can cause 

errors in Cluster Manager. 



� A user tries to access a port and is denied access to the port. (This can happen when a 

user tries to execute a service not allowed on the port.) This type of alarm event is 

sometimes called a port access exception. 

� A port cannot be started. The most common reason a port cannot start is that the port 

is being accessed by another application. 

� A service cannot be loaded or executed due to setup errors. For a flow service, a 

possible error is a missing XML metafile. For a Java service, possible errors include a 

missing class file or method. 

You can use alarm events to invoke event handlers that execute when the server generates 

messages related to the status of the server. For example, you might want to create an 

event handler that notifies the administrator when a user is denied access to the server or 

to a port, when a service fails to load or execute, or when a port does not start. You can 

also create event handlers to send data to a network monitoring system. 

Building Handlers for Alarm Events 

When the Event Manager invokes an event handler for an alarm event, the event handler 

receives an IData object containing the following run-time data. (A specification and IS 

document type for these parameters are provided in the pub.event folder.) 


time A String containing the date and time that the alarm event occurred, in 

the format yyyy/MM/dd HH:mm:ss.SS 

service A String containing the fully qualified name of the service that generated 

the event. A service can generate an alarm event when a client invokes a 

service that accesses information or a service on a remote server. If the 

client is not a member of an allowed group for the port on the remote 

server, the service will generate an alarm event. 

sessionID A String containing the identification number for the session during 

which the alarm event was generated. Some alarm events are not 

generated during sessions. In these cases, the sessionID variable will not 

contain a value. 

msg A String containing the error message from the alarm event. 

Tip! When you subscribe an event handler to an alarm event, you can create a filter for the 

msg field to be more selective about the alarm events that invoke the event handler. 


Working with Audit Events 


An audit event occurs when a service generates audit data. You can use the options in a 

service’s Audit properties to specify when a service generates audit data. A service can 

generate audit data once, twice, or zero times during execution. You can use audit events 

to invoke other services when a particular service executes. For example, you might want 

an audit event generated for a critical service to invoke a logging service or a notification 

service. For more information about specifying when a service generates audit data, see 

“Configuring Service Auditing” on page 148. 

Building Handlers for Audit Events 

When the Event Manager invokes an event handler for an audit event, the event handler 

receives an IData object that contains the following run-time data. (A specification and an 

IS document type for the input data are provided in the pub.event folder.) 


time A String containing the date and time the event occurred. By default, the 

format is yyyy-MM-dd HH:mm:ss z. You can set the format by specifying 

the watt.server.dateStampFmt property. For instructions about how to 

specify server property settings, see the webMethods Integration Server 


threadID A String containing the hash identifying the server thread that generated 

the audit event. 

service A String containing the fully qualified name of the service that generated 

the event. 

ssnid A String containing the identification number for the session of the service 

that generated the event. 

result A String indicating the audit point. Will be one of the following: 

String Description 

Started This event marks the beginning of a service. 

Ended This event marks the end of a service that executed 

successfully. 




Failed This event marks the end of a service that executed 

unsuccessfully (that is, threw an exception) and is not 

configured to retry or has exhausted all retries. 

Note: To capture details about any exception that is thrown 

when a service fails, you must subscribe to Exception Events. 

For information about Exception Events, see the following 

section. 

Retried A retried event will be created each time a service is retried. 

Events are only created for a service if auditing for that type 

of event is enabled for the service (for example, start events 

will not be created unless auditing for service start is enabled 

for that service). 

pipeline A copy of the state of the pipeline at the point where the event occurred. 

Note that this element is only included in the input object if the Include 

pipeline property is set to Always or On errors only or if the watt.server.auditLog 

server property is set to verbose. For more information about the Include 

pipeline property in the Audit category of the Properties panel, see 

“Including the Pipeline in the Audit Log” on page 151. 

user A String containing the user name that invoked the service that generated 

the event. 

The audit event handlers that you build can make use of these inputs as they need to. 

Keep in mind that when the service’s Log on option is set to Error, success, and start an audit 

event handler is called twice each time a service runs: once when the service starts and 

again when it ends. Your event handler can check the value of the result parameter to 

determine whether it is processing an audit event from before or after the service 

executed. For more information about the Log on property in the Audit category of the 

Properties panel, see “Specifying When Audit Data Is Generated” on page 149. 

Also, if your event handler needs data from the invoking service’s pipeline, make sure that 

service’s Include pipeline option is set to Always or On errors only. Otherwise, the pipeline 

element won’t be included in the input object that is passed to your event handler. 

Tip! When you subscribe an event handler to an audit event, you can create a filter for the 

service field to specify the services whose audit events you want to subscribe to. That is, 

you can specify which services’ audit events invoke the event handler. 


Working with Exception Events 


An exception event occurs when a service throws an exception (including when a flow 

service “exits on failure”). You can use exception events to invoke some prescribed action, 

such as notifying an administrator, when a particular service fails. 

Note: Keep in mind that event handlers are processed independently of the services that 

invoke them. They are completely separate, asynchronous processes. Event handlers are 

not designed to replace the error handling and/or error recovery procedures that you 

would normally include in your service. 

If a nested service throws an exception, an exception event is generated by each service in 

the call stack. For example, if service A1 calls service B1, and B1 throws an exception, both 

B1 and A1 generate exception events (in that order). 

Building Handlers for Exception Events 

When the Event Manager invokes an event handler for an exception event, the event 

handler receives an IData object containing the following run-time data. (A specification 

and an IS document type for this signature reside in the pub.event folder.) 


time A String containing the date and time the event occurred. By default, the 

format is yyyy-MM-dd HH:mm:ss z. You can set the format by 

specifying the watt.server.dateStampFmt property. For instructions 

about how to specify server property settings, see the webMethods 

Integration Server Administrator’s Guide. 

error A String containing the error message from the exception. 

localizedError A String containing the error message text in the language that 

corresponds to your locale. 

errorType A String containing the exception type that was thrown. 

errorDump A String containing more detailed information about the exception (if 

the exception object contains dump information). 

service A String containing the fully qualified name of the service that 

generated the event. 

user A String containing the user that requested the service that generated 

this event. 

callStack A document (IData object) containing the items in the call stack. See the 

pub.event:callStackItem IS document type for the definition of the 

documents in callStack. 



Working with Guaranteed Delivery Events 


pipeline A copy of the state of the pipeline at the point when the exception 

occurred. 

threadID A String identifying the thread that invoked the service. 

ssnid A String containing the identification number of the session during 

which the exception occurred. 

errorMsgID A String containing the identification number for the error message. 

errorDetails A document (IData object) containing additional exception information 

provided by the author of the Java service. For more information about 

constructing exceptions to return additional information, see the 

webMethods Integration Server Java API Reference for the 

com.wm.util.LocalizedException class. 

nestedErrorInfo A document (IData object) containing any nested errors and exceptions. 

See the pub.event:exceptionInfo IS document type for the definition of the 

items in nestedErrorInfo. 

Tip! When you subscribe an event handler to an exception event, you can create a filter for 

the service field to specify the services whose exception events you want to subscribe to. 

That is, you can specify which services’ exception events invoke the event handler. 

A guaranteed delivery event occurs when a client uses guaranteed delivery to invoke a 

service on a remote Integration Server, and when the server returns the service results to 

the requesting client. There are two types of guaranteed delivery events: 

� GD Start events occur when a client uses guaranteed delivery to invoke a service on a 

remote the Integration Server. In a flow service, executing the pub.remote.gd:start service 

generates a GD Start event. 

� GD End events occur when a client receives the results of the service it requested using 

guaranteed delivery. In a flow service, executing the pub.remote.gd:end service generates 

a GD End event. 

Each guaranteed delivery transaction generates a GD Start event and a GD End event. You 

can subscribe to GD Start and GD End events to invoke event handlers that log 

guaranteed delivery transactions to a file or database. You might also want to use 

guaranteed delivery events to invoke event handlers that send notification. For example, 

if you use guaranteed delivery to invoke a service that processes purchase orders, you 

might want to send notification to a business account manager about purchase orders 



from a particular client, or when the value of a purchase order is greater than a certain 

amount. 

Guaranteed Delivery Events and Transaction Events 

Guaranteed delivery events are related to transaction events (Tx Start and Tx End). 

Guaranteed delivery events begin when a client requests a guaranteed delivery 

transaction (GD Start) and when the client receives the results of the guaranteed delivery 

transaction (GD End). Transaction events occur when a service invoked using guaranteed 

delivery begins executing (Tx Start event) and when the service finishes executing (Tx End 

event). 

The following diagram illustrates when guaranteed delivery events and transaction 

events occur during a guaranteed delivery transaction. In the following scenario, a local 

Integration Server uses guaranteed delivery to invoke a service on a remote server. 

A Guaranteed Delivery Transaction generates Guaranteed Delivery Events and Transaction Events 


1 

2 

3 

webMethods Integration 

Server (local) 

Service A 

1 2 

5 4 3 

webMethods Integration 

Server (remote) 

Service B 

Service A uses guaranteed delivery to invoke Service B on the remote 

Integration Server. When the local server requests Service B, the local server 

generates a GD Start event. By default, the GD Start event is logged to the 

txoutyyyymmdd.log file. 

The remote Integration Server receives the request and begins executing 

Service B. When the remote server begins executing Service B, the remote 

server generates a Tx Start event. By default, the Tx Start event is logged to the 

txinyyyymmdd.log file. 

The remote Integration Server finishes executing Service B and generates a Tx 

End event. By default, the Tx End event is logged to the txinyyyymmdd.log file. 



4 

5 


The remote Integration Server sends the results of Service B to the requesting 

client (here, the local Integration Server). 

The local Integration Server receives the results of Service B and generates a 

GD End event. By default, the GD End event is logged to the 

txoutyyyymmdd.log file. 

For more information about guaranteed delivery, see the Guaranteed Delivery Developer’s 


Building Handlers for Guaranteed Delivery Start Events 

When the Event Manager invokes an event handler for a GD Start event, the event handler 

receives an IData object containing the following run-time data. (A specification and an IS 

document type for these parameters reside in the pub.event folder.) 


time A String containing the date and time that the event occurred, in the 

format yyyy/MM/dd HH:mm:ss.SS. 

TID A String containing the transaction identification number of the service 

that generated the GD Start event. 

svcname A String containing the name of the service invoked using guaranteed 

delivery. 

result A String containing the status of the guaranteed delivery transaction, such 

as NEW. 

Tip! When you subscribe an event handler to a GD Start event, you can create a filter for 

the svcname field to specify the services in a guaranteed delivery transaction that you want 

to subscribe to. That is, you can specify the services that when invoked using guaranteed 

delivery will invoke the event handler. 



Building Handlers for Guaranteed Delivery End Events 

When the Event Manager invokes an event handler for an GD End event, the event 


and an IS document type for these parameters reside in the pub.event folder.) 


time A String containing the date and time that the event occurred, in the format 

yyyy/MM/dd HH:mm:ss.SS. 

TID A String containing the transaction identification number of the service that 

generated the GD End event. 


as DONE. 

Working with Port Status Events 

A port status event occurs each time the Integration Server updates the server statistics. 

The port status event provides current status information about all of the configured ports 

on the Integration Server. 

You can use port status events to invoke services that send port status data to a network 

monitoring system. You can also use port status events to invoke services that write port 

status data to a log file. 

Note: The watt.server.stats.pollTime property determines the frequency with which the 

Integration Server updates server statistics. The default frequency is 60 seconds. If you 

change this value, you must restart the Integration Server for the change to take effect. For 

more information about this property, see the webMethods Integration Server Administrator’s 



Building Handlers for Port Status Events 


When the Event Manager invokes an event handler for a port status event, the event 

handler receives an IData object that contains the following run-time data. 

(A specification and an IS document type with these parameters are provided in the 

pub.event folder.) 


portStatusInfo A document reference list containing status information for each 

configured port on the Integration Server. 


Working with Replication Events 

time A String containing the date and time that the event 

occurred, in the format yyyy/MM/dd HH:mm:ss.SS. 

port A String containing the number for the port. 

status A String indicating the status of the port. 

protocol A String indicating the type of port (for example, http, 

https, ftp, or e-mail). 

primary A String indicating the primary port. By default, the 

Integration Server designates an HTTP port at port 5555 

as the primary port. 

enabled A String indicating whether or not the port is enabled. 

The value will be one of the following: 

A replication event occurs when the pub.replicator:generateReplicationEvent service executes. 

You might want to generate and subscribe to replication events to invoke event handlers 

that automate the completion of the package replication and distribution processes. For 

example, you could create replication event handlers that do the following: 

� Notify package subscribers when a package is published. 

� Maintain a log of replicated packages. 


true The port is enabled. 

false The port is disabled. 

� Maintain a log of the packages distributed or “pushed” to your subscribers. 

� Maintain a log of the packages your partners pulled from you. 



For more information about the pub.replicator:generateReplicationEvent service, see the 

webMethods Integration Server Built-In Services Reference. 

Building Handlers for Replication Events 

When the Event Manager invokes an event handler for a replication event, the event 

handler receives an IData object that contains the following run-time data. (A specification 

and an IS document type for these parameters are provided in the pub.event folder.) 




action A user-defined String describing the action (such as create or push) for 

the replication event. You can use the value of the action variable to 

maintain separate logs for each action type. 

package A String containing the name of the released or pushed package. 

service A String containing the name of the flow service that invoked the 

pub.replicator:generateReplicationEvent service. 

Tip! When you subscribe an event handler to a replication event, you can create a filter to 

specify the package that, when replicated, will invoke the event handler. 

Working with Session Events 

A session event occurs when a client starts or ends a session on the Integration Server or 

when the Integration Server terminates an inactive session. You can subscribe to any of the 

following types of session events: 

� Session Start events occur when a developer uses Developer to open a session on the 

Integration Server or when an IS client opens a session on the server to execute 

services. 

� Session End events occur when a developer or IS client specifically issues a disconnect 

instruction to the Integration Server. 

� Session Expire events occur when the Integration Server terminates an inactive session. 

You can subscribe to session events to invoke event handlers that maintain your own log 

files or to invoke event handlers that send notification about users opening sessions on the 

server. 


Building Handlers for Session Start Events 


When the Event Manager invokes an event handler for a session start event, the event 




time A String containing the date and time the event occurred, in the 


sessionID A String containing the identification number of the session. 

userid A String containing the user ID that the IS client or developer used to 

log on to the Integration Server. 

sessionName A String containing the name of the new session. 

Tip! When you subscribe an event handler to a Session Start event, you can create a filter so 

that only session start events generated by a specific user or by a member of a specific 

group invoke the event handler. 

Building Handlers for Session End Events 

When the Event Manager invokes an event handler for a session end event, the event 







rpcs A String containing the number of service calls performed during the 

session. 

age A String identifying how long the session existed (in milliseconds) 

before it ended. 


Building Handlers for Session Expire Events 


When the Event Manager invokes an event handler for a session expire event, the event 




time A String containing the date and time the event occurred, in the 



rpcs A String containing the number of service calls performed during the 

session. 

age A String identifying how long the session existed (in milliseconds) 

before it expired. 

Working with Stat Events 

A stat event occurs each time the Integration Server updates the statistics log (stats.log). 

The statistics log maintains statistical information about the consumption of system 

resources. The watt.server.stats.pollTime property determines the frequency with which the 

Integration Server updates statistics. The default frequency is 10 seconds. 

You can use stat events to invoke event handlers that maintain your own log file or to 

invoke event handlers that send server statistics to a network monitoring system. 

Note: The Integration Server provides an agent that you can configure for use with a 

network monitoring system. For information about implementing this agent, see the 

readme file in the agentInstall.jar file located in the webMethods6\IntegrationServer\lib 

directory. 


Building Handlers for Stat Events 


When the Event Manager invokes an event handler for a stat event, the event handler 




startTime A String containing the date and time that the event occurred, in the 


uptime A String identifying the length of time the server has been running, in 

the format yyyy/MM/dd HH:mm:ss.SS. 

totalMem A String identifying the total amount of used and unused storage 

space available (in kilobytes) to the Integration Server. 

freeMem A String identifying the amount of unused storage space available (in 

kilobytes) to the Integration Server. 

usedMem A String identifying the amount of storage used (in kilobytes) by the 


freeMemPer A String identifying the percentage of free memory. 

usedMemPer A String identifying the percentage of used memory. 

svrT A String identifying the number of executing services. 

svrTMax A String identifying the maximum number of services that executed 

concurrently during the previous poll cycle. 

sysT A String identifying the number of threads in use. 

sysTMax A String identifying the maximum number of threads that executed 


conn A String identifying the number of current sessions on the Integration 

Server. 

connMax A String identifying the maximum number of connections that ran 


reqTotal A String identifying the total number of requests during the poll 

cycle. 

reqAvg A String identifying the average processing duration for a service 

during the previous poll cycle. 

newReqPM A String identifying the new requests per minute at the beginning of 

the poll cycle. 

endReqPM A String identifying the new requests per minute at the end of the 

poll cycle. 



Working with Transaction Events 


errSvc A String identifying the number of services that completed with 

errors since the Integration Server started. 

svcRate A String identifying the number of service starts and ends per second 

during the last poll cycle. 

ssnUsed Number of licensed sessions currently active. 

ssnPeak Greatest number of licensed sessions that have run concurrently on 

the server. 

ssnMax Maximum number of sessions for which the server is licensed. 

errSys A String identifying the number of errors that were not caused by 

services in the previous poll cycle. 

A transaction event occurs when an Integration Server begins and finishes executing a 

guaranteed delivery transaction. There are two types of transaction events: 

� Tx Start events occur when an Integration Server begins executing a service invoked 

with guaranteed delivery. 

� Tx End events occur when an Integration Server finishes executing a service invoked 

with guaranteed delivery. 

Transaction events result from guaranteed delivery transactions. Each guaranteed 

delivery transaction generates a Tx Start event and a Tx End event. In fact, the transaction 

events occur between the guaranteed delivery events. A Tx Start event occurs 

immediately after a GD Start event and a Tx End event occurs immediately before a GD 

End event. For more information about how transaction events relate to guaranteed 

delivery events, see “Guaranteed Delivery Events and Transaction Events” on page 378. 

You can subscribe to Tx Start and Tx End events to invoke event handlers that log 

guaranteed delivery transactions to a file or database. You might also want to use 

transaction events to invoke event handlers that send notification. 


Building Handlers for Transaction Start Events 


When the Event Manager invokes an event handler for a Tx Start event, the event handler 






TID A String containing the transaction ID for the guaranteed delivery 

transaction that generated the event. 


as NEW. 

Building Handlers for Transaction End Events 

When the Event Manager invokes an event handler for a Tx End event, the event handler 




time A String containing the date and time that the event occurred, in the format 

yyyy/MM/dd HH:mm:ss.SS. 

TID A String containing the transaction ID of the guaranteed delivery 

transaction that generated the event. 


as DONE. 




Chapter 15. Building Services that Retry 

� Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

� Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 

� Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 


Overview 

15. Building Services that Retry 

When creating a service, you can construct and configure the service to retry 

automatically if a transient error occurs during service execution. A transient error is an 

error that arises from a temporary condition that might be resolved or restored, such as 

the unavailability of a resource due to network issues or failure to connect to a database. 

The service might execute successfully if the Integration Server waits a short interval of 

time and then retries the service. 

To signal the Integration Server to re-execute the service, you can build the service to 

throw an ISRuntimeException when a transient error occurs. Then, if a service ends 

because of an ISRuntimeException and you set retry properties for the service (or the 

trigger calling the service), the Integration Server will re-execute the service using the 

original service input. 

This appendix provides guidance for building flow services that retry if a transient error 

occurs during service execution. 

Requirements for Retrying 

If you want a service to catch a transient error, re-throw it as an ISRuntimeException, and 

then re-execute, the following criteria must be met: 

� You must configure the Retry on ISRuntimeException properties for the top-level service. 

For more information about configuring service retry and how the Integration Server 

retries services, see “Configuring Service Retry” on page 143. 

� If the service functions as a trigger service (the service is invoked by a trigger), you 

must configure the Retries on error properties for the trigger. For more information 

about configuring trigger retries and how the Integration Server retries trigger 

services, see the Publish-Subscribe Developer’s Guide. 

� If the service is a flow service, the service must invoke pub.flow:throwExceptionForRetry. 

� If the service is written in Java, the service can use 

com.wm.app.b2b.server.ISRuntimeException(). 

Adapter Services and Retry Behavior 

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. At run time, adapter services detect if their back-end 

server is down or the network connection is broken. The adapter service propagates an 

exception that is based on ISRuntimeException. This behavior allows for the automatic 

retry when the service is invoked by a trigger or invoked within a flow that is configured 

to retry when an ISRuntimeException occurs. 



Note: If you invoke an adapter service within a flow service that uses the try-catch 

structure, and the try contains an adapter service, make sure that the catch structure can 

interpret the adapter service exception that signals a retry. You must ensure that the error 

evaluating logic in the catch structure can account for the adapter service exception that 

signals a retry. If it does not, the Integration Server will not retry the flow service. For 

details about building a flow service that throws an ISRuntimeException, see “Building a 

Service that Throws an Exception for Retry”, below. 

For more information about adapter services, see the relevant adapter guides. 

Building a Service that Throws an Exception for Retry 

A flow service that will be retried if a transient error occurs during service execution 

consists of the following basic sections of logic: 

� A try sequence that executes the work that you want the service to perform. 

� A catch sequence that handles any exception that occurs during the try sequence, 

determines if a transient error caused the exception, and indicates whether the 

Integration Servers should retry the service. 

� An outer sequence that exits successfully if either the try sequence or catch sequence 

succeeds. 

� A throw exception for retry block that executes only if the catch block indicated that 

the service should be retried. 

Note: This section describes one possible way to build a service that throws an exception 

for retry. 

How to Build a Service that Throws an Exception for Retry 

The following describes the general steps that you take to build a service that will retry if 

a transient error occurs during service execution. 

1 Insert a SEQUENCE step. This SEQUENCE step will act as the outer sequence for the try 

sequence and the catch sequence. 

Set this outer SEQUENCE to exit on SUCCESS. This indicates that the sequence will 

exit when any child step in the sequence succeeds. If the inner try sequence (the first 

child of this parent SEQUENCE) succeeds, then the inner catch sequence will be 

skipped, an ISRuntimeException will not be thrown, and the entire service will have 

executed successfully. 



2 Insert an inner SEQUENCE step for the try sequence. This sequence will contain the logic 

that you want the service to perform. 

Set this inner try sequence to exit on FAILURE. This indicates that the try sequence 

will exit when a step in the SEQUENCE fails. The Integration Server will then execute 

the next step in the flow service, which is the catch sequence. 

Make sure that the try sequence is a child of the outer sequence that you inserted in 

step 1. 

3 Insert the logic that you want the service to perform. These steps contain the work that you 

want the service to do. 

Make sure to indent the steps below/under the try SEQUENCE step. 

4 Insert a SEQUENCE step for the catch sequence. This sequence contains the steps needed 

to catch the exception, determine its cause, and then determine whether the service 

can be retried. 

Set the catch sequence to exit when DONE. This indicates that the Integration Server 

executes every step in the catch sequence, even if one of the steps fails. 

Make sure that the catch sequence is a child of the outer sequence that you inserted in 

step 1. 

5 Invoke pub.flow:getLastError in the catch sequence to retrieve error information. This service 

retrieves information about the last exception that occurred in the flow service. In this 

case, the pub.flow:getLastError service retrieves information about the error that caused 

the try sequence to fail. 

Make sure to indent the pub.flow:getLastError invoke step below the catch SEQUENCE 

step. 

Using pub.flow:getLastError to catch the error information is optional. 

Important! The pub.flow:getLastError service must be the first service invoked within the 

catch sequence. If it is not the first service invoked, and a preceding service in the 

catch sequence fails, the error thrown in the try sequence will be overwritten with the 

new error. 

6 Insert error evaluation logic. This logic should do the following: 

� Determine whether the last error is a transient error that can be retried. 

Note: If the flow service includes an adapter service, and a transient error occurs 

during adapter service execution, the adapter service throws an exception that 

extends the ISRuntimeException. 



� If the service can be retried, set a flag to indicate this. For example, you might set 

a variable named isTransientError to “true”. A subsequent BRANCH step will use 

the flag to determine whether to execute the pub.flow:throwExceptionForRetryService. 

Keep in mind that you might need to use more than one service to handle the error, 

determine if it was caused by a transient error, and set the transient error flag. 

Make sure to insert the exception evaluation logic within the catch sequence, but after 

the pub.flow:getLastError service. 

7 Insert a BRANCH step that branches on the value of the transient error flag. This BRANCH 

step will determine if an ISRuntimeException should be thrown. You can branch on a 

switch value or branch on an expression. Do one of the following: 

. 

� If you are branching on a switch value, in the Switch property, specify the name of 

the pipeline variable whose value will act as the switch. For example, if you use 

the isTransientError variable as the flag to indicate that a transient error occurred, 

you would use isTransientError as the switch. 

� If you are branching on an expression, set the Evaluate labels property to True. 

Important! You must position the BRANCH step so that it is outside of the try and catch 

sequences and is a sibling of the outer sequence. This is because exceptions thrown 

within a sequence are ignored and the BRANCH step will contain the 

pub.flow:throwExceptionForRetry service. 

8 Invoke the pub.flow:throwExceptionForRetry service. This service wraps an exception and 

rethrows it as an ISRuntimeException. 

Assign this service a label that indicates that this step should execute when the 

transient error flag is true. For example, if you built the BRANCH step to use 

isTransientError is set to true when a transient error occurred and you want the 

Integration Server to retry the service, set the Label property to: true. 

Make sure that this step is a child of the BRANCH step. 


You can also provide the following optional parameters to the 

pub.flow:throwExceptionForRetry service. 



wrappedException An Object containing any exception that you want to include 

as part of this ISRuntimeException. This might be the 

exception that causes the pub.flow:throwExceptionForRetry service 

to execute. For example, if the service attempts to connect to a 

database and the connection attempt fails, you might map the 

exception generated by the database connection failure to the 

wrappedException parameter. 

message A string containing a message to be logged as part of this 

exception. 

Note: If you want to insert retry logic into a service that makes database calls or involves 

transactions, your service needs to include logic for starting, committing, and rolling back 

the transaction. Specifically, the rollback call should be made in the catch sequence. 

Example—Building a Service that Throws an Exception for 

Retry 

The following flow service executes a nested service, catches any exception that occurs, 

determines if a transient error caused the exception, and, if necessary, throws an 

ISRuntimeException so that the entire service can be retried. 

Trying a service, catching an error, and throwing an exception for retry 


# Description 


Step 1 Create outer SEQUENCE that exits on SUCCESS. This step creates a sequence that 

wraps the try sequence and the catch sequence. The sequence is set to exit on 

success so that the outer sequence will exit when a child step executes 

successfully. That is, setting the outer sequence to exit on success allows the 

outer sequence to exit without executing the catch sequence when the try 

sequence succeeds. 

Step Description 

1.1 Create try SEQUENCE that exits on FAILURE. This step creates the try 

sequence that contains all of the logic you want the service to execute. 

This step is set to exit on failure so that the Integration Server will 

execute the next step (the catch sequence) within the outer sequence. 


1.1.1 Insert service logic. This step represents the logic that you want 

the service to perform. In many services, the service logic 

might consist of multiple services or flow steps. 

If the try sequence executes successfully, the entire outer 

sequence exits. The Integration Server skips the catch 

sequence because the outer sequence exits upon the success of 

any child step (in this case, the try sequence). The Integration 

Server then executes the next step in the flow service (the 

BRANCH on ‘/isTransientError’ step). 

If an error occurs while executing this step, the try sequence 

exits (it is set to exit on FAILURE), and the Integration Server 

executes the catch sequence. 

1.2 Create catch SEQUENCE that exits on DONE. This step creates the catch 

sequence that contains the logic that should be performed when an 

error occurs during the try sequence. This step contains logic that 

evaluates the error to determine whether the entire service can be 

retried. 

The catch sequence is set to exit on DONE. This means that the 

Integration Server executes all the steps in the catch sequence. The 

Integration Server considers the catch sequence to be successful after 

all the child steps execute. Because the catch sequence is successful, the 

outer sequence exits (it is set to exit on SUCCESS), and the Integration 

Server executes the next step in the flow service. 

To determine whether a transient error occurred, this step contains the 

following steps. 


# Description 



1.2.1 Catch the last error. This step invokes the pub.flow:getLastError 

service to catch the error that caused the try sequence to fail. 

1.2.2 Determine if error was a transient error. This step evaluates the 

contents of the lastError document returned by the 

pub.flow:getLastError service to determine whether the try 

sequence failed because of a transient error. In many services, 

you might use multiple services or flow steps to determine 

whether a transient error occurred. 

1.2.3 Set flag to indicate whether service should retry. This step sets the 

transient error flag to indicate if a try sequence failed because 

of a transient error. In this case, if a transient error occurred, 

the transient error flag (the variable isTransientError) is set to 

“true”. 

After this step executes, the Integration Server exits the catch 

sequence, exits the outer sequence, and then executes the next 

step in the flow service (the BRANCH on ‘/isTransientError’ 

step). 

Step 2 Check transient error flag. This step specifies that the value of the isTransientError 

variable should be used to determine whether the service should throw an 

ISRuntimeException. 

If the try sequence executed successfully, the Integration Server falls through 

to the end of the service because the value of the switch variable does not 

match any of the target steps (if the try sequence succeeded, isTransientError is 

null). In this case, the Integration Server considers the execution of the flow 

service to be successful. 


2.1 Throws ISRuntimeException. This step executes the 

pub.flow:throwExceptionForRetry service if the value of isTransientError is 

“true”. This service wraps the exception generated by the transient 

error in the try sequence and rethrows it as an ISRuntimeException. 

The Integration Server will retry the service. 


Appendix A. webMethods Flow Steps 

� BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 

� EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

� INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

� LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 

� MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

� REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 

� SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 


BRANCH 

A. webMethods Flow Steps 

The BRANCH step selects and executes a child step based on the value of one or more 

variables in the pipeline. You indicate the variables you want to branch on by specifying a 

switch value or by writing an expression that includes the variables. 

Branching on a Switch Value 

When you branch on a switch value, you specify the switch variable in the Switch property 

of the BRANCH step. In the Label property for each child step, you specify the value of the 

switch variable that will cause that child step to execute. At run time, the BRANCH flow 

step executes the child step that has the same label as the value of the Switch property. 

If you want to execute a child step when the value of the Switch property is an empty 

string, leave the Label property of the child step blank. If you want to execute a child step 

when the Switch property is a null or unmatched string, set the Label of the child step to 

$null or $default. 

BRANCH flow step using a switch 

Name of the 

switch field is 

choice 

if the value of choice is ‘Name1’ 

if the value of choice is ‘Name2’ 

if the value of choice is ‘NameN’ 

if choice does not exist or has a 

value of ‘$null’ 

if the value of choice is an empty 

string “ “ 

Otherwise 


Name1 

Name2 

NameN 

$null 

no label 

$default

Branching on Expressions 


When you branch on expressions, you set the Evaluate labels property of the BRANCH step 

to true. In the Label property for each child step, you write an expression that includes one 

or more variables. At run time, the BRANCH step executes the first child step with an 

expression that evaluates to true. 

If you want to specify a child step to execute when none of the expressions are true, set the 

label of the child step to $default. 

BRANCH step using expressions 

Evaluate labels 

is set to true 

if the expression of first child is true 

if the expression of second child is true 

if the expression of n th child is true 

Otherwise 

The BRANCH step in the following illustration evaluates expressions to determine which 

child steps execute. The run-time value of BuyerAccount, PromotionalCode, or 

shippingMethod determines the shipping charges added to an order. 

Simple BRANCH step using expressions 


Child1 

Child2 

ChildN 

$default

Properties 

The BRANCH step has the following properties. 


Conditions that Will Cause a BRANCH Step to Fail 


Comments Optional. Specifies a descriptive comment for the step. 

Scope Optional. Specifies the name of a document (IData object) in the 

pipeline to which you want to restrict this step. If you want this step to 

have access to the entire pipeline, leave this property blank. 

Timeout Optional. Specifies the maximum number of seconds that this step 

should run. If this time elapses before the step completes, the server 

waits for the step to complete and then raises an exception. 

If you want to use the value of a pipeline variable for this property, 

type the variable name between % symbols. For example, 

%expiration%. 

If you do not need to specify a time-out period, leave Timeout blank. 

Label Optional. (Required if you are using this BRANCH step as a target for 

another BRANCH or EXIT step.) Specifies a name for this instance of 

the BRANCH step, or a null, unmatched, or empty string ($null, 

$default, blank). 

Switch Specifies the String field that the BRANCH step uses to determine 

which child flow step to execute. The BRANCH step executes the child 

flow step whose label matches the value of the field specified in the 

Switch property. Do not specify a value if you set the Evaluate labels 

property to True. 

Evaluate labels Specifies whether or not you want the server to evaluate labels of child 

steps as conditional expressions. When you branch on expressions, 

you enter expressions in the Label property for the children of the 

BRANCH step. At run time, the server executes the first child step 

whose label evaluates to True. To branch on expressions, select True. To 

branch on the Switch value, select False. 

� The switch field is not in the pipeline and the BRANCH step does not contain a 

default child step or a child step to handle null values. 

� The matching child step fails. 

� The BRANCH step does not complete before the time-out period expires. 


EXIT 


The EXIT step exits the entire flow service or a single flow step. Specifically, it may exit 

from the nearest ancestor loop step, a specified ancestor step, the parent step, or the entire 

flow service. 

The EXIT step can throw an exception if the exit is considered a failure. When an 

exception is thrown, user-specified error message text is displayed by typing it directly or 

by assigning it to a variable in the pipeline. 

Properties 

The EXIT step has the following properties. 



Label Optional. (Required if you are using this EXIT step as a target for a 

BRANCH step.) Specifies a name for this specific step, or a null, 


Exit from Required. Specifies the flow step or service from which you want to 

exit. 

Specify this value… To exit the… 

$parent Parent flow step, regardless of the type of step. 

$loop Nearest parent LOOP or REPEAT step. 

$flow Entire flow. 

label Nearest ancestor step that has a label that 

matches this value. 

Note: If the label you specify does not match the 

label of an ancestor flow step, the flow will exit 

with an exception. 


INVOKE 


Examples of When to Use 

� Exit an entire flow service from within a series of deeply nested steps. 


Signal Required. Specifies whether the exit is considered a success or a 

failure. A SUCCESS condition exits the flow service or step. A 

FAILURE condition exits the flow service or step and throws an 

exception. The text of the exception message is contained in the 

Failure message property. 

Failure message Optional. Specifies the text of the exception message that is 

displayed when Signal is set to FAILURE. If you want to use the value 

of a pipeline variable for this property, type the variable name 

between % symbols. For example, %mymessage%. 

� Throw an exception when you exit a flow service or a flow step without having to 

write a Java service to call Service.throwError( ). 

� Exit a LOOP or REPEAT flow step without throwing an exception. 

The INVOKE flow step invokes another service. You can use it to invoke any type of 

service, including another flow service. 

Properties 

The INVOKE step has the following properties. 



Scope Optional. Specifies the name of a document (IData object) in the pipeline 

to which you want to restrict this step. If you want this step to have 


Timeout Optional. Specifies the maximum number of seconds that this step 

should run. If this time elapses before the step completes, the server 

waits for the step to complete and then raises an exception. 

If you want to use the value of a pipeline variable for this property, type 

the variable name between % symbols. For example, %expiration%. 



LOOP 


Conditions that Will Cause an INVOKE Step to Fail 

� The service that is invoked fails. 

� The specified service does not exist. 

� The specified service is disabled. 


Label Optional. (Required if you are using this step as a target for a BRANCH 

or EXIT step.) Specifies a name for this specific step, or a null, 


Service Required. Specifies the fully qualified name of the service to invoke. 

Validate 

input 

Validate 

output 

Optional. Specifies whether the server validates the input to the service 

against the service input signature. If you want the input to be validated, 

select True. If you do not want the input to be validated, select False. 

Optional. Specifies whether the server validates the output of the service 

against the service output signature. If you want the output to be 

validated, select True. If you do not want the output to be validated, select 

False. 

The LOOP step takes as input an array variable that is in the pipeline. It loops over the 

members of an input array, executing its child steps each time through the loop. For 

example, if you have a service that takes a string as input and a string list in the pipeline, 

use the LOOP step to invoke the service one time for each string in the string list. 

You identify a single array variable to use as input when you set the properties for the 

LOOP step. You can also designate a single variable for output. The LOOP step collects an 

output value each time it runs through the loop and creates an output array that contains 

the collected output values. If you want to collect more than one variable, specify a 

document that contains the fields you want to collect for the output variable. 


The LOOP step 

input is 

an array 

Properties 

The LOOP step has the following properties. 




Scope Optional. Specifies the name of a document (IData object) in the pipeline to 

which you want to restrict this step. If you want this step to have access to 

the entire pipeline, leave this property blank. 

Timeout Optional. Specifies the maximum number of seconds that this step should 

run. If this time elapses before the step completes, the server waits for the 

step to complete and then raises an exception. 




Label Optional. (Required if you are using this step as a target for a BRANCH or 

EXIT step.) Specifies a name for this specific step, or a null, unmatched, or 

empty string ($null, $default, blank). 

Input array Required. Specifies the input array over which to loop. You must specify a 

variable in the pipeline that is an array data type (that is, String list, String 

table, document list, or Object list). 

Output 

array 

No 

more input 

array 

members? 

Yes 

get next 

member of 

input array 

child child child 

Optional. Specifies the name of the field in which the server places output 

data for an iteration of the loop. The server collects the output from the 

iterations into an array field with the same name. You do not need to 

specify this property if the loop does not produce output values. 


MAP 

Conditions that Will Cause a LOOP Step to Fail 

� The pipeline does not contain the input array. 

� The input field is not an array field. 

� A child step of the LOOP step fails during any iteration of the loop. 

� The LOOP step does not complete before the time-out period expires. 


The MAP step adjusts the pipeline at any point in a flow. It makes pipeline modifications 

that are independent of an INVOKE step. 

Within the MAP step, you can: 

� Link (copy) the value of a pipeline input field to a new or existing pipeline output 

field. 

� Drop an existing pipeline input field. (Keep in mind that once you drop a field from 

the pipeline, it is no longer available to subsequent services in the flow.) 

� Assign a value to a pipeline output field. 

� Perform document-to-document mapping in a single view by inserting transformers. 

Properties 

The MAP step has the following properties. 


Comments Optional. Specifies a descriptive comment for this step. 

Scope Optional. Specifies the name of a document (IData) in the pipeline to 










REPEAT 


Example of When to Use 





� You want to assign an initial set of input values in a flow service (that is, to initialize 

variables). You insert the MAP step at the beginning of the flow, and then use the Set 

Value modifier to assign values to the appropriate variables in Pipeline Out. 

� You want to map a document from one format to another (for example, cXML to 

XML). Insert transformers into the MAP step to perform the needed data 

transformations. For more information about transformers, see “What Are 

Transformers?” on page 222. 

The REPEAT step repeatedly executes its child steps up to a maximum number of times 

that you specify. It determines whether to re-execute the child steps based on a Repeat on 

condition. You can set the repeat condition to one of the following: 

� Repeat if any one of the child steps fails. 

� Repeat if all of the elements succeed. 

You can also specify a time period that you want the REPEAT flow step to wait before it 

re-executes its child steps. 

The REPEAT step 

reps=0 

wait for 

repeat 

interval 

child 

reps = reps + 1 

Yes 

child 

reps < Count ? 

Exit 

No 


Yes 

child 

Repeat 

condition 

met? 

No 

Exit

Properties 

The REPEAT step has the following properties. 
















Count Required. Specifies the maximum number of times the server re-executes 

the child steps in the REPEAT step. Set Count to 0 (zero) to instruct the 

server that the child steps should not be re-executed. Set Count to a value 

greater than zero to instruct the server to re-execute the child steps up to a 

specified number of times. Set Count to -1 to instruct the server to reexecute 

the child steps as long as the specified Repeat on condition is true. 

Repeat 

interval 


the variable name between % symbols. For example, %servicecount%. 

Optional. Specifies the number of seconds the server waits before reexecuting 

the child steps. Specify 0 (zero) to re-execute the child steps 

without a delay. 


the variable name between % symbols. For example, %waittime%. 

Repeat on Required. Specifies when the server re-executes the REPEAT child steps. 

Select SUCCESS to re-execute the child steps when the all the child steps 

complete successfully. Select FAILURE to re-execute the child steps when 

any one of the child steps fails. 


SEQUENCE 

When Does REPEAT Fail? 

The following conditions cause the REPEAT step to fail: 

If “Repeat on” is set to… The REPEAT step fails if… 

SUCCESS A child within the REPEAT block fails. 


FAILURE The Count limit is reached before its children execute 

successfully. 

If the REPEAT step is a child of another step, the failure is propagated to its parent. 

Examples of When to Use 

� “Repeat on” property is set to FAILURE. Use when a service accesses a remote server and 

you want the service to retry if the server is busy. Make the service that accesses the 

remote server a child element of a REPEAT flow step, and then set the Repeat on 

property to FAILURE. If the service attempts to access the Web site and it fails, the 

REPEAT flow step attempts to retry the service again. You also set a Repeat interval that 

causes the REPEAT flow condition to wait a period of time before invoking the service 

again. 

� “Repeat on” property is set to SUCCESS. Use in a Web-automation service when you want 

to repeat a load and query step and a “Next Page” button exists in the current 

document, indicating that there are additional pages to be processed. End the 

REPEAT flow step when the query step fails to retrieve a “Next Page” button in the 

current document. 

The SEQUENCE step forms a collection of child steps that execute sequentially. This is 

useful when you want to group a set of steps as a target for a BRANCH step. 

You can set an exit condition that indicates whether the sequence should exit prematurely 

and, if so, under what condition. Specify one of the following exit conditions: 

� Exit the sequence when a child step fails. Use this condition when you want to ensure that 

all child steps are completed successfully. If any child step fails, the sequence ends 

prematurely and the sequence fails. 

� Exit the sequence when a child step succeeds. Use this condition when you want to define 

a set of alternative services, so that if one fails, another is attempted. If a child step 

succeeds, the sequence ends prematurely and the sequence succeeds. 



� Exit the sequence after executing all child steps. Use this condition when you want to 

execute all of the child steps regardless of their outcome. The sequence does not end 

prematurely. 

The SEQUENCE step 

First... 

Properties 

If exit condition 

is not met... 

child child child 

The SEQUENCE step has the following properties. 









If you want to use the value of a pipeline variable for this property, type the 

variable name between % symbols. For example, %expiration%. 





Exit on Required. Specifies when to exit the SEQUENCE step. 

Specify this value... To... 

If exit condition 

is not met... 




FAILURE Exit the sequence when a child step fails. (Execution 

continues with the next flow step in the flow service.) 

Conditions that Will Cause the SEQUENCE Step to Fail 

This section describes the conditions that cause failure based on the exit condition for the 

sequence. 

If Exit on is set to FAILURE, conditions that will cause a failure include: 

� One of the child steps fails. 

� The SEQUENCE step does not complete before the time-out period expires. 

If Exit on is set to SUCCESS, conditions that will cause a failure include: 

� All the child steps fail. 

The SEQUENCE step executes its child steps until 

either one fails or until it executes all its child steps. 

This is the default. 

Note: When a SEQUENCE step exits on failure, the 

Integration Server rolls back the pipeline contents. That 

is, the Integration Server returns the pipeline to the 

state it was in before the SEQUENCE step executed. 

SUCCESS Exit the sequence when a child step executes 

successfully or after all child steps fail. (Execution 

continues with the next flow step in the flow service.) 

DONE Exit the sequence after all child steps execute. 

The SEQUENCE step executes all of its child steps 

regardless of whether they succeed or fail. 


If Exit on is set to DONE, conditions that will cause a failure include: 



Appendix B. Regular Expressions 

� What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 

� Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 

� Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 


What Is a Regular Expression? 

B. Regular Expressions 

A regular expression is a pattern-matching technique used extensively in UNIX 

environments. webMethods Developer lets you use regular expressions to specify 

pattern-matching strings for some of its functions. For example, you can use a regular 

expression to specify an index, a property, or a mask in a webMethods Query Language 

(WQL) statement. You can also use a regular expression to specify the switch value for a 

BRANCH step. 

To specify a regular expression, you must enclose the expression between / symbols. 

When the server encounters this symbol, it knows to interpret the characters between 

these symbols as a pattern-matching string (that is, a regular expression). 

A simple pattern-matching string such as /string/ matches any element that contains 

string. So, for example, the regular expression /webMethods/ would match all of the 

following strings: 

“webMethods” 

“You use webMethods Integration Server to execute services” 

“Exchanging data with XML is easy using webMethods” 

“webMethods Integration Server” 

Important! Characters in regular expressions are case sensitive. 

Using a Regular Expression in a Mask 

When you use a regular expression as a mask, you use parenthesis to specify which 

characters you want to collect. For example, the object reference: 

doc.p[].text[/(.{30}).*/] 

retains the first 30 characters in each matching element and discards the rest. 


Regular Expression Operators 


Following are the operators supported in the webMethods implementation of regular 

expressions. 

Use this 

symbol… To… 

. Match any single character except a new line. 

Example doc.p[/web.ethods/].text 

This example would return any paragraph containing the string ‘web’ 

followed by any single character and the string ‘ethods’. It would match 

both ‘webMethods’ and ‘webmethods’. 

^ Match the beginning of the string or line. 

Example doc.p[/^webMethods/].text 

This example would return any paragraph containing the string 

‘webMethods’ at the beginning of the element or at the beginning of any 

line within that element. 

$ Match the end of the string or line. 

Example doc.p[/webMethods$/].text 


‘webMethods’ at the end of the paragraph element or at the end of any 


* Match the preceding item zero or more times. 

Example doc.p[/part *555-A/].text 

This example would return any paragraph containing the string ‘part’ 

followed by zero or more spaces and then the characters ‘555-A’. 

+ Match the preceding item 1 or more times. 

Example doc.p[/part +555-A/].text 


followed by one or more spaces and then the characters ‘555-A’. 

? Match the preceding item 0 or 1 times. 

Example doc.p[/part ?555-A/].text 


followed by zero or one space and then the characters ‘555-A’. 


Use this 



( ) When used in an index, these characters group an item within the regular 

expression. 

Example doc.p[/part(,0)+May/].text 


followed by one or more occurrences of the characters ‘,0’ and then the 

characters ‘May”. 

When used in a mask, they specify characters that you want to retain. 

Example doc.p[].text[(^.{25}).*] 

This example would keep the first 25 characters within each paragraph 

and discard the rest. 

{n } Match the preceding item exactly n times. 

Example doc.p[/^.{24}webmethods/].text 

This example would return any paragraph in which the word 

‘webmethods’ started in the 25th character position of the paragraph. 

{n ,} Match the preceding item n or more times. 

Example doc.p[/^.{10,}webmethods/].text 


‘webmethods’ appeared anywhere after the 10th character position of the 

paragraph. That is, this example would return a paragraph in which the 

word ‘webmethods’ started in the 11th or later character position of the 

paragraph. 

{0,m } Match the preceding item none or at most m times. 

Example doc.p[/^.{0,4}webmethods/].text 


‘webmethods’ started in any of the first 5 character positions of the 

paragraph. 

{n ,m } Match the preceding item at least n times, but not more than m times. 

Example doc.p[/^.{1,4}webmethods/].text 


‘webmethods’ started in character position 2 through 5 of the paragraph. 


Use this 


| Match the expression that precedes or follows this character. 

Example doc.p[/webmethods|webMethods/].text 


This example would return any paragraph that contained either 

‘webmethods’ or ‘webMethods’. 

\b Match a word boundary. 

Example doc.p[/\bport\b/].text 

This example would return any paragraph that contained the word ‘port’, 

but not paragraphs that contained these characters as part of a larger 

word, such as ‘import’, ‘support’, ‘ports’ or ‘ported’. 

\B Match a boundary that is not a word boundary. 

Example doc.p[/\B555-A/].text 

This example would return any paragraph that contained the characters 

‘555-A’ as part of a larger word such as AZ555-A, or Dept555-A, but not 

‘555-A’ alone. 

\A Match only at the beginning of a string (equivalent to ^). 

Example doc.p[/\AwebMethods/].text 


‘webMethods’ at the beginning of the element or at the beginning of any 


\Z Match only at the end of a string (or before a new line at the end). 

Example doc.p[/webMethods\Z/].text 


‘webMethods’ at the end of the paragraph element or at the end of any 


\n Match a new line. 

Example doc.p[/webMethods\n/].text 


‘webMethods’ followed by the new line character. 

\r Match a carriage return. 

Example doc.p[/webMethods\r/].text 


‘webMethods’ followed by a carriage return. 


Use this 


\t Match a tab character. 

Example doc.p[/\twebMethods/].text 



‘webMethods’ preceded by a tab character. 

\f Match a form feed character. 

Example doc.p[/webMethods\f/].text 


‘webMethods’ followed by a form feed character. 

\d Match any digit. Same as [0-9]. 

Example doc.p[/part \d555-A/].text 

This example would return any paragraph containing a part number that 

starts with any digit 0 through 9, and is followed by the characters 555-A. 

Therefore, it would match ‘part 1555-A’ but not ‘part A555-A’ or ‘part 

#555-A’. 

\D Match any non-digit. Same as [^0-9]. 

Example doc.p[/part \D555-A/].text 


starts with any character other than 0 through 9, and is followed by the 

characters 555-A. Therefore, it would match ‘part A555-A’ and ‘part #555- 

A’, but not ‘part 1555-A’. 

\w Match any word character. Same as [0-9a-z_A-Z]. 

Example doc.p[/part \w4555-A/].text 


starts with a letter or digit and is followed by the characters 555-A. 

Therefore, it would match ‘part A555-A’ and ‘part 1555-A’, but not ‘part 

#555-A’. 

\W Match any nonword character. Same as [^0-9a-z_A-Z]. 

Example doc.p[/part \W4555-A/].text 


starts with a character other than a letter or digit, and is followed by the 

characters 555-A. Therefore, it would match ‘part #555-A’ and ‘part -555- 

A’, but not ‘part 1555-A’ or ‘part A555-A’. 


Use this 


\s Match any white-space character. Same as [\t\n\r\f]. 

Example doc.p[/\swebMethods/].text 



‘webMethods’ if it is preceded by a tab character, a new line character, a 

carriage return, or a form-feed character. 

\S Match any nonwhite-space character. Same as [^\t\n\r\f]. 

Example doc.p[/\SwebMethods/].text 


‘webMethods’, if that string is not preceded by a tab character, a new line 

character, a carriage return, or a form-feed character. 

\0 Match a null string. 

Example doc.p[/[^\0]/].text 

This example would return any paragraph that is not empty (null). 

\xnn Match any character with the hexadecimal value nn. 

Example doc.p[/\x1FwebMethods/].text 

This example would return any paragraph containing the ASCII unitseparator 

character (1F) followed by the characters ‘webMethods’. 

[ ] Match any character within the brackets. 

Example doc.p[/part [023]555-A/].text 


starts with the numbers 0, 2, or 3 and is followed by the characters 555-A. 

Therefore, it would match ‘part 0555-A’ and ‘part 2555-A’, but not ‘part 

4555-A’. 

The following characters have special meaning when used within 

brackets: 

Use this char… To… 

^ Exclude characters from the pattern. 

Example doc.p[/part [^023]555-A/].text 

This example would return any paragraph containing a 

part number that does not start with the numbers 0, 2, 

or 3, but is followed by the characters 555-A. Therefore, 

it would match ‘part 4555-A’ and ‘part A555-A’, but not 

‘part 0555-A’. 


Use this 


- Specify a range of allowed characters. 

Example doc.p[/part [A-M]555-A/].text 


This example would return any paragraph containing a 

part number that starts with any letter A through M 

and is followed by the characters 555-A. Therefore, it 

would match ‘part A555-A’ and ‘part J555-A’, but not 

‘part N555-A’. 


Appendix C. Supported Data Types 

� Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 

� Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . 424 


Data Types 

C. Supported Data Types 

Data is passed in and out of a service through an IData object. An IData object is the 

collection of name/value pairs on which a service operates. An IData object can contain 

any number of elements of any valid Java objects, including additional IData objects and 

IDataCodable objects. 

Each element stored in an IData object corresponds to a data type. The following table 

identifies the data types supported by Developer. 

Data Type Icon Description Java Type 

String String of characters. java.lang.String 

String list A one-dimensional String 

array. 

String table A two-dimensional String 

array. 

Document A data structure that is a 

container for other variables. 

Documents can contain 

variables of any other data 

type. The contents of a 

document (IData object) are 

stored as key/value pairs 

where the variable name is 

the key. 

Document list A one-dimensional array of IS 

document types (IData [ ]or 

Values [ ]). 

Document 

reference 

Document 

reference list 

A document whose structure 

is defined by an IS document 

type. 

A document list whose 

structure is defined by an IS 


java.lang.String[ ] 

java.lang.String[ ][ ] 

com.wm.data.IData 

com.wm.util.Values 

For more information, see 

the webMethods Integration 

Server Java API Reference. 

com.wm.data.IData [ ] 

com.wm.util.Values [ ] 

com.wm.util.Table 

Reference to an existing 

object which implements 

the com.wm.data.IData 

interface or a reference to 

an existing 

com.wm.util.Values object. 

Reference to an existing 

object which implements 

the com.wm.data.IData 

interface or a reference to 

an existing 

com.wm.util.Values object. 


Data Type Icon Description Java Type 

Object A data type that does not fall 

into any of the data types 

described in the above rows, 

and is not declared to be one 

of the basic Java classes 

supported natively by 

Integration Server. This icon 

is used for Objects of 

unknown type. 

Object list An array of Objects of 

unknown type. 

Java Classes for Objects 


Any subclass of 

java.lang.Object. 

You can further describe the contents of an Object or Object list variable by applying a 

Java class to the variable. When you apply a supported Java class to an Object or Object 

list variable, Developer changes the icon for the variable. Applying Java classes to Objects 

and Object lists can provide the following benefits: 

� Other developers can easily see the types your service expects as inputs and produces 

as output. 

� Other developers can easily see the types contained in an IS document type. 

� You can input values for the variable when testing and debugging. 

Example 

java.util.InputStream 

An array of any subclass of 

java.lang.Object. 

Example 

java.util.InputStream[ ] 

Note: You can view the actual data types represented by Object or Object list icons in 

built-in services by looking up the service in the webMethods Integration Server Built-In 


Note: Developer displays small symbols next to a variable icon to indicate validation 

constraints. Developer uses to indicate an optional variable. Developer uses the ‡ 

symbol to denote a variable with a content constraint. For information about applying 

constraints to variables, see “Applying Constraints to Variables” on page 261. 

� You can assign values to variables in the pipeline using the Set Value modifier. 



Note: When you input values for a constrained Object during testing or when assigning a 

value in the pipeline, Developer validates the data to make sure it is of the correct type. 

The following table identifies the Java classes you can apply to Objects and Object list 

variables in Developer. 

Data Type Icon Description Java Class 

boolean True or false. java.lang.Boolean 

boolean list A one-dimensional boolean 

array. 

byte Signed integer. The value 

must be greater than or equal 

to –128 but less than or equal 

to 127. 

java.lang.Boolean[ ] 

java.lang.Byte 

byte [ ] A one-dimensional byte array. primitive type 

byte list A one-dimensional byte array. java.lang.Byte[ ] 

character A single unicode character. java.lang.Character 

character list A one-dimensional character 

array. 

java.lang.Character[ ] 

date Date and time. java.util.Date 

date list A one-dimensional date array. java.util.Date[ ] 

double Double-precision floating 

point number. 

double list A one-dimensional double 

array. 

float Standard-precision floating 

point number. 

java.lang.Double 

java.lang.Double[ ] 

java.lang.Float 

float list A one-dimensional float array. java.lang.Float[ ] 

integer Signed integer. The value 


to -2147483647 but less than 

or equal to 2147483647. 

java.lang.Integer 


Data Type Icon Description Java Class 

integer list A one-dimensional integer 

array. 

long Signed integer. The value 


to 

–9223372036854775808 but 

less than or equal to 

9223372036854775807. 

How webMethods Developer Supports Tables 


java.lang.Integer[ ] 

java.lang.Long 

long list A one-dimensional long array. java.lang.Long[ ] 

short Signed integer. The value 


to -32768 but less than or 

equal to 32767. 

short list A one-dimensional short 

array. 

java.lang.Short 

java.lang.Short[ ] 

Note: Object and Object list variables constrained with a Java classes should be linked only 

to other Object and Object list variables of the same Java class or of unknown type. 

Although Developer permits a link between constrained Objects of different Java classes, 

the run-time behavior is undefined. For more information about specifying Java classes 

for Objects, see “Considerations for Object Constraints” on page 263. 

With the exception of String table, Developer does not provide a separate data type for 

tables. However, tables can appear as document lists or Objects. Tables that are instances 

of com.wm.util.Table appear as document lists in webMethods Developer. These tables 

can be used as document lists in flow services. Services in the WmDB package use tables 

that are instances of wm.com.util.Table. 

Tables can also be declared as Objects. Objects or user-defined table-like objects that do 

not implement the com.wm.util.pluggable.WMIDataList interface appear as Objects of 

unknown type in webMethods Developer. 



Default Pipeline Rules for Linking to and from Array Variables 

When you create links between scalar and array variables, you can specify which element 

of the array variable you want to link to or from. Scalar variables are those that hold a 

single value, such as String, IS document type, and Object. Array variables are those that 

hold multiple values, such as String list, String table, document list, and Object list. For 

example, you can link a String to the second element of a String list. 

If you do not specify which element in the array variable that you want to link to or from, 

Developer uses the default rules on the Pipeline tab to determine the value of the target 

variable. The following table identifies the default pipeline rules for linking to and from 

array variables. 

If you link… To… Then… 

A scalar 

variable 

An array variable that is 

empty (the variable does not 

have a defined length) 


A scalar 

variable 

value [empty] value 

value X 

Y 

Z 

An array variable with a 

defined length 

The link defines the length of the 

array variable; that is, it contains 

one element and has length of one. 

The first (and only) element in the 

array is assigned the value of the 

scalar variable. 

The length of the array is preserved 

and each element of the array is 

assigned the value of the scalar 

variable. 

value 

value 

value 



An array 

variable 

X 

Y 

Z 


A scalar variable The scalar variable is assigned the 

first element in the array. 


An array 

variable 

X 

Y 

Z 

[empty] X 

An array variable that does 

not have a defined length 

[empty] X 

Y 

Z 

The link defines the length of the 

target array variable; that is, it will 

be the same length as the source 

array variable. The elements in the 

target array variable are assigned 

the values of the corresponding 

elements in the source array 

variable. 



An array 

variable 

X 

Y 

Z 

V 

W 

X 

Y 

Z 

An array variable that has a 

defined length 

A 

B 

C 

A 

B 

C 


The length of the source array 

variable must equal the length of the 

target array variable. If the lengths 

do not match, the link will not 

occur. If the lengths are equal, the 

elements in the target array variable 

are assigned the values of the 

corresponding elements in the 

source array variable. 

No link occurs. 

Note: A source variable that is the child of a document list is treated like an array because 

there is one value of the source variable for each document in the document list. For 

example: 


X 

Y 

Z

If you link... To... 

DocumentList1 

String1 

Where the value of DocumentList1 is... Then the value of StringList1 is… 

DocumentList1 

DocumentList1 [0] 

String1 

a 


String1 b 


String1 c 

StringList1 

StringList1 



a 

b 

c



Appendix D. Conditional Expressions 

� Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 

� Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 

� Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 

� Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

� Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

� Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 


Overview 

D. Conditional Expressions 

webMethods Integration Server provides syntax and operators that you can use to create 

expressions for use with the BRANCH step, pipeline mapping, and in trigger conditions. 

� In a BRANCH step, you can use an expression to determine the child step that 

webMethods Integration Server executes. At run time, the Integration Server executes 

the first child step whose conditional expression evaluates to “true”. For more 

information about the BRANCH step, see “The BRANCH Step” on page 168 

� In pipeline mapping, you can place a condition on the link between variables. At run 

time, webMethods Integration Server only executes the link if the assigned condition 

evaluates to “true.” For more information about applying conditions to links between 

variables, see “Applying Conditions to Links Between Variables” on page 214. 

� In triggers, you can further refine a subscription by creating filters for the publishable 

document types. A filter specifies criteria for the contents of a document. At run time, 

the Broker or Integration Server applies the filter to the document. The Broker or 

Integration Server will route or process the document only if the document meets the 

filter criteria. For more information, see the Publish-Subscribe Developer’s Guide. 

Important! If multiple conditions in the trigger specify the same publishable document 

type, the filter applied to the publishable document type must be the same in each 

condition. 

When you write expressions and filters, keep the following points in mind: 

� Operators, variable names, and strings are case sensitive. 

� White space between the tokens of an expression is ignored. 

� Some syntax that is valid on the Integration Server is not valid on the Broker. If the 

syntax is valid for a Broker, the Integration Server saves the filter with the 

subscription on the Broker. If the syntax is not valid, the Integration Server saves the 

subscription without the filter on the Broker. Subscriptions and filters are always 

saved on the Integration Server. 

For a list and an example of syntax that prevents a filter from being saved on the 

Broker, see “Rules for Use of Expression Syntax with the Broker” on page 444. 


Syntax 


When you create an expression, you need to determine which values to include in the 

expression. Values can be represented as variable names, regular expressions, numbers, 

and strings. The following table identifies the types of values you can use in an expression 

and the syntax for each value type. 

Value Type Syntax Description 

Regular 

Expression 

Variable variableName 

/regularExpression/ Pattern-matching string. Use the following syntax 

for pattern matching of variable values: 

–OR– 

%variableName% 

variableName = /regularExpression/ 

For more information about regular expressions, see 

Appendix B, “Regular Expressions”. 

Example Explanation 

sku = /^WM[0-9]+/ Evaluates to true if the 

sku variable has a value 

that starts with “WM” 

and is followed by one 

or more digits (WM001, 

WM95157) 

Variable name. For information about how to use 

this syntax to address children of other variables or 

elements of array variables, see “Addressing 



price Value of the price 

variable 

%address/postalCode% Value of the postalCode 

variable in the address 

document 

%poItems[0]% Value of the first element 

in the poItems array 


Value Type Syntax Description 

String "string" 

–OR– 

'string' 


Literal string. Use this value type to compare the 

value of a variable to a string. 


“Favorite Customer” Value is the literal string 

“Favorite Customer” 

‘Favorite Customer’ Value is the literal string 

“Favorite Customer” 

Note: Strings not enclosed in quotes (' or ") are 

interpreted as variable names. 

Number number Number. The following examples indicate the 

accepted number formats: 

Examples Explanation 

-10, 5, 100 Integers 

5.0, 6.02 Floating point number 

(java.lang.Double) 

6.345e+4 Scientific notation 

Null $null Variable is null or missing. Typically compared with 

a variable name to determine if the variable is null 

or missing from the input data. 


%quantity% = $null Evaluates to true if the 

quantity variable is 

missing from the input 

data or is null 


Comparing Java Objects to Constants 


If you want to create a conditional expression that compares a constrained Java Object to a 

constant value, you must use the following syntax to represent the constant value: 

If the object is 

constrained as type... Use this syntax... 

Boolean "true" or "false" 

Byte "xx" 

Example: %myBoolean%=="true" 

The string constant in the expression is case insensitive. For 

example, the expressions %myBoolean%=="true" and 

%myBoolean%=="tRUe" are equivalent. 

Example: "10" (for 0X0A) 

Character "a" 

Example: "C" 

Double xxxxxx.x or xxxxxx or -xxxxxx 

Example: 123456.0, 123456, -123456 

Float xxxx.x or -xxxx.x 

Example: 1234.1, -1234.1 

Integer xxxxx or -xxxxx 

Example: 12345, -12345 

Long xxxxxx or -xxxxxx 

Example: 123456 or -123456 

Short xxx or -xxx 

Example: 123 or -123 

Date "yyyy-MM-dd HH:mm:ss timezone" 

Example: "2002-06-25 00:00:00 EDT" 


Operators 

Checking for Variable Existence 


Sometimes you might want to create an expression that checks only for the existence of a 

variable or checks to see whether a variable is null. The following table describes the 

syntax used to check for variable existence. 

To see if… Use this syntax… Description 

Variable 

exists 

Variable does 

not exist 

Expressions can include relational and logical operators. Relational operators are used to 

compare values to each other. Logical operators are used to combine multiple expressions 

into a single condition. 

Relational Operators 

variableName Evaluates to true if the specified variable exists and 

has a non-null value. 

This example... Evaluates to true if... 

customerID The customerID variable exists 

and is not null. 

!variableName Evaluates to true if the specified variable does not 

exist or is null. 


!quantity The quantity variable does not 

exist or is null. 

!color & !size The color variable does not exist 

or is null and the size variable 

does not exist or is null. 

You can use relational operators to compare the value of two fields or you can compare 

the value of a field with a constant. The Integration Server provides two types of relational 

operators: standard and lexical. 

� Standard relational operators can be used in expressions and filters to compare the 

contents of fields (variables) with other variables or constants. 

� Lexical relational operators can be used to compare the contents of fields (variables) 

with string values in trigger filters. 

Relational operators are sometimes called comparison operators. 



Note: You can also use standard relational operators to compare string values. However, 

filters that use standard relational operators to compare string values will not be saved 

with the trigger subscription on the Broker. If the subscription filter resides only on the 

Integration Server, the Broker automatically places the document in the subscriber’s 

queue. The Broker does not evaluate the filter for the document. The Broker routes all of 

documents to the subscriber, creating greater network traffic between the Broker and the 

Integration Server and requiring more processing by the Integration Server. 

Standard Relational Operators 

You can use the standard relational operators to compare the contents of a variable with 

any type of value (numerical, string, Boolean, dates, etc.) or another variable. 

When comparing strings using the standard operators, the Integration Server uses a 

binary code point comparison algorithm. In this algorithm, the Integration Server 

compares each byte in the first string with each byte in the second string to determine 

which string is numerically greater. For example, “A” has a value of 65 and “a” has a value 

of 97, so “a” is greater than “A”. 

Keep the following points in mind when using standard relational operators to compare 

strings: 

� The Integration Server considers A to be the lowest letter and Z to be the highest (for 

example, A < B, A < Z, B > A, Z > A). 

� The Integration Server considers lowercase letters to be greater than the matching 

uppercase letter (for example, a > A, A < a, a < B, c > A). 

The following table identifies the standard relational operators you can use in expressions 

and filters. 

Operator Syntax Description 

= a = b Equal to. 


customerID = 

"webMethods" 

== a == b Equal to. 

The value of the customerId 

variable is “webMethods.” 

This example... Evaluates to true if.. 

sku == "WM001" The value of the sku variable is 

“WM001.” 



!= a != b Not equal to. 



quantity != 0 The value of the quantity variable 

does not equal 0 (zero). 

a b Not equal to. 


state 'ME' The value of the state variable does 

not equal ME (Maine). 

> a > b Greater than. 


price > 100 The value of the price variable is 

greater than 100. 

%companyID% > "Acme" The value of the companyID 

variable is greater than Acme. 

>= a >= b Greater than or equal to. 


%totalPrice% >= 100 The value of the totalPrice variable 

is greater than or equal to 100. 

companyID >= "Acme" The value of the companyID 

variable is greater than or equal to 

Acme. 

< a 


quantity < 5 The value of the quantity variable is 

less than 5. 

companyID < "Acme" The value of the companyID 

variable is less than Acme. 



The following table describes the lexical operators that you can use in filters. 

Operator Description 

L_EQUALS Lexical equal to. 


%myString% L_EQUALS 

"abc" 

L_NOT_EQUALS Lexical not equal to. 


The value of the myString 

variable is abc. 


%myString% L_NOT_EQUALS 

"abc" 

L_LESS_THAN Lexical less than. 


variable is not abc. 


%myString% L_LESS_THAN 

"abc" 

L_LESS_OR_EQUAL Lexical less than or equal to. 


variable is less than abc. 


%myString% 

L_LESS_OR_EQUAL "abc" 

L_GREATER_THAN Lexical greater than. 


variable is less than or equal 

to abc. 


%myString% 

L_GREATER_THAN "abc" 

L_GREATER_OR_EQUAL Lexical greater than or equal to. 


variable is greater than abc. 


%myString% 

L_GREATER_OR_EQUAL "abc" 


variable is greater than or 

equal to abc. 


Logical Operators 


You can use the following logical operators in expressions to create conditions consisting 

of more than one expression: 


! ! expr Negates the next expression. 


! (%sku% = "WM001") The value of the sku variable is 

not equal to WM001. 

not not expr Negates the next expression. 


not (color = "blue") The color variable is not equal to 

blue. 

| expr | expr Logical *OR. True if either of the expressions is true. 

|| expr || 

expr 

or expr or 

expr 


%color% = "blue" | 

%color% = "red" 

The value of the color variable is 

blue or red. 

Logical OR. True if either of the expressions is true. 


totalPrice > 1000 || 

customerID = 

'Favorite 

Customer' 

The value of the totalPrice 

variable is greater than 1000 or 

the value of the customerID 

variable equals Favorite 

Customer. 

Logical OR. True if either of the expressions is true. 




creditCardNum = $null 

or 

cardExpireDate = 

$null 

or cardExpireDate = 20 && 

totalPrice >= 100 

The value of the quantity 

variable is greater than or equal 

to 20 and the value of the 

totalPrice variable is greater 

than or equal to 100. 

Logical AND. Both expressions must evaluate to true for the 

entire condition to be true. 


!color and !size The color variable does not exist 

in the input or is null and the 

size variable does not exist in 

the input or is null. 


Precedence 

Addressing Variables 


webMethods Integration Server evaluates expressions in a condition according to the 

precedence level of the operators in the expressions. 

The following table identifies the precedence level of each operator you can use in an 

expression. 

Precedence Level Operators 

1 ( ) 

2 not, ! 

3 =, ==, !=, , >, >=,

Use this notation… To… 

Notes: 


arrayVariableName[index] Address an element in an array. 

Example: orderItems[0] 

Value of the first element in the 

orderItems array. 

arrayVariableName[rowIndex][columnIndex] Address an element in a 

two-dimensional array (String table). 

Example: dictionary[1][2] 

Value of the element located in the 

third column of the second row in the 

dictionary array. 

duplicateVariableName(index) Address an occurrence of a variable 

where there are multiple variables 

with the same name in the document 

or pipeline. The index is zero-based. 

Example: address(1) 

Value of the second variable named 

address. 

%"variableWithSpecialCharacters"% Address a variable whose name 

contains special characters. Variables 

that contain special characters must be 

enclosed in quotation marks. 

Example: %"address(work)"% 

Value of the variable named 

address(work). 

For more information, see 

“Addressing Variables that Contain 

Special Characters” below. 

� To view the path to a variable in the pipeline, rest the mouse pointer over the variable 

name. Developer displays the variable path in a tool tip. 

� To copy the path to a variable in a pipeline, select the variable, right-click, and select 

Copy. 

� You can enclose variable names in %, for example %buyerInfo/state%. If the variable 

name includes special characters, you must enclose the path to the variable in % 



(percent) symbols and enclose the variable name in " " (quotation marks). For more 

information about using variables as values in expressions, see “Syntax” on page 431. 

Addressing Variables that Contain Special Characters 

If a variable name contains any of the special characters listed in below, you need to use 

the following notation to address the variable: 

� Enclose the path to the variable and the variable name in % (percent symbols). 

� Enclose the variable name that contains special characters in " (quotation marks). 

Following are some examples of how to address variables that contain special characters. 

Type... To... 

%"Date/Time"% Address a variable named Date/Time. 

%purchaseOrder/"Date/Time"% Address a variable named Date/Time in the 

document variable purchaseOrder. 

Typing Special Characters in Expressions 

Note: If you did not enclose Date/Time in 

quotation marks, and instead had 

%purchaseOrder/Date/Time% or 

%"purchaseOrder/Date/Time"%, the 

expression would address a variable named 

Time in a document named Date that was 

contained in a document named 

purchaseOrder. 

%"address(work)"/"phone(cell)"% Address a variable named phone(cell) in the 

document variable address(work). 

%"Date\\Time"% Address a variable named Date\Time. 

You enter most of the special characters in an expression just as you would enter them 

when creating the variable name. However, for three of the special characters (the 

backslash, percent symbol, and quotation marks), you need to use a combination of keys. 

The following table identifies the special characters for variable names and any key 

sequences that you need to use to enter a variable name with that character in an 

expression. 


Character Character Name Special sequence 

\ backslash \\ 

[ opening bracket 

] closing bracket 

( opening parenthesis 

) closing parenthesis 

% percent \% 

" quotation marks \" 

/ slash mark (forward) 

Rules for Use of Expression Syntax with the Broker 


Important! When you use variable names with special characters in expressions or filters, 

you must enclose the variable name in " " (quotation marks). 

When you create filters for documents in trigger conditions, keep in mind that some 

syntax that is valid on the Integration Server is not valid on the Broker. When you save a 

trigger, the Integration Server and the Broker evaluate the filter to make sure that it uses 

proper syntax. If the syntax is valid on the Broker, the Broker saves the subscription and 

the filter. If the syntax is invalid on the Broker, the Integration Server automatically 

removes the filter before the Broker saves the subscription. The filter will only be saved on 

the Integration Server. 

Note: The Broker saves as much of a filter as possible with the subscription. For example, 

suppose that a filter consists of more than one expression, and only one of the expressions 

contains syntax the Broker considers invalid. The Broker saves the expressions it considers 

valid but does not save the expression containing invalid syntax. (The Integration Server 

saves all the expressions.) 

Keep the following points in mind when writing filters for triggers: 

� Expressions that specify field names that contain syntax, characters, symbols, or 

words the Broker considers restricted or reserved will not be saved on the Broker. 

� All expressions must contain a relational (comparison) operator. 

� Use lexical relational operators (such as L_EQUALS, L_LESS_THAN) to compare fields of 

type String. 



� Use standard relational operators (such as =, ==, !=, , =) to compare fields 

that are not of type String. 

� Use the =, ==, , or != operators to compare a value with an Object constrained as a 

Boolean. 

The following table identifies syntax that the Broker considers invalid. Expressions with 

this syntax will be saved on the Integration Server but not on the Broker. 

Tip! You can use the Broker Administrator to view the filters (expressions) saved with a 

subscription. If the expression does not appear with the subscription on the Broker, then 

the expression contains invalid syntax. 

The Broker considers expressions invalid 

when they contain.... Examples 

Field names with syntax, characters, 

symbols, or words the Broker considers 

restricted or reserved 

No comparison operators "fieldName" 

"!fieldName" 

A standard relational operator to 

compare fields of type String 

A lexical relational operator to compare 

fields that are not of type String 

A field of type String compared with a 

numeric value 

Operators other than =, ==, !=, or to 

compare an Object constrained as a 

Boolean with a value 

An Object constrained as a Boolean 

compared with a field of type String 

eventtype L_EQUALS “addEmployee” 

tax% < 5 

Note: Although the Broker considers a 

field name that contains the % symbol to 

be invalid, you can use the % symbol to 

enclose field names in the expression. 

%myString% < "yourString" 

%price% L_LESS_THAN 50 

"stringName" > 12 

myBoolean

The Broker considers expressions invalid 

when they contain.... Examples 

A $null token %fieldName% = $null 


A reference to an array field stringList[1] L_EQUALS "a" 

Regular expressions that contain back 

references 

Regular expressions that use quantifiers 

other than +, ?, and * 

Regular expressions that use extended 

metacharacters 

fieldName = /^(a|b)\1$/ 


/a{1}/ 

/a{1,5}/ 

fieldName = /\w/

Appendix E. jcode tags 

� jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 

� jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 


jcode Template 

E. jcode tags 

The following code provides a template describing the tags (highlighted) that the jcode 

utility uses to identify code segments in a Java source file. 

package Interface1; 

/** 

* This is an example of an empty Java source code file, 

* properly annotated for use with the jcode utility. 

*/ 

import com.wm.app.b2b.server.Service; 

import com.wm.app.b2b.server.ServiceException; 

import com.wm.data.IData; 

import com.wm.data.IDataCursor; 

// --- --- 

// --- --public 

class Interface0 

{ 

public static void Service1 (IData pipeline) 


{ 

// --- --- 

// --- --return; 

} 

public static void Service2 (IData pipeline) 


{ 

// --- --- 

// --- --return; 

} 

// --- --- 

// --- --- 

} 


jcode Example 

The following is a complete example of properly commented Java source code. 

Sample Code—IData 

E. jcode tags 

The following is an example of a class whose services (methods) take IData objects as 

input. 

package recording; 

/** 

* This is an example of Java source code properly annotated 

* for use with the IS jcode utility. Note that, unless 

* noted otherwise, all comments will be stripped out of this 

* file during the process of fragmenting the code. 

*/ 

/** 

* == IMPORTS == 

* All your imports should be wrapped with the START-IMPORTS 

* and END-IMPORTS tags. 

*/ 

// --- --import 

com.wm.app.b2b.server.Service; 

import com.wm.app.b2b.server.ServiceException; 

import com.wm.data.IData; 

import com.wm.data.IDataCursor; 

import com.wm.data.IDataUtil; 

import java.util.*; 

// --- --- 

/** 

* == CLASS NAMING == 

* This class contains the definition of all the Java services 

* within the recording.accounts interface (note the recording 

* package declaration up top). Note that each service is 

* defined by a method with the same name. 

*/ 

public class accounts 

{ 

/** 

* == INDIVIDUAL SERVICES == 

* The createAccount service. This service expects three 

* parameters -- a string ("name"), a string array ("references"), 

* and a document type. It returns two strings ("message" and "id"). 

* 

* Note the special tags delimiting the start and end of the 

* service. The two lines immediately before start tag and after 

* the end tags are mandatory. 

* 

* Also note the use of comments to establish a signature for the 

* service. Each signature line has the following format: 

* 

* [direction] type:dimension:option name 

* 

* direction: "i" (input) or "o" (output) 


* type: 

* field (corresponds to instances of java.lang.String) 

* document type (corresponds to instances of com.wm.data.IData) 

* object (corresponds to instances of any other class) 

* option: 

* required (this parameter is mandatory) 

* optional (this parameter is optional) 

* name: the name of the parameter 

* 

* To indicate nesting, use a single "-" at the beginning of 

* each line for each level of nesting. 

*/ 

public static void createAccount (IData pipeline) 


{ 

// --- --- 

// [i] field:0:required name 

// [i] field:1:required references 

// [i] record:0:required data 

// [i] - field:1:required address 

// [i] - field:1:required phone 

// [o] field:1:required message 

// [o] field:1:required id 

IDataCursor idc = pipeline.getCursor(); 

String name = IDataUtil.getString(idc, "name"); 

String [] refs = IDataUtil.getStringArray(idc, "references"); 

IData data = IDataUtil.getIData(idc, "data"); 

E. jcode tags 

// Do something with the information here. Note that this 

// comment inside the service body is the only one that won't 

// get discarded when fragmenting the service (i.e., it will 

// show up in Developer.) 

idc.last(); 

idc.insertAfter ("message", "createAccount not fully implemented"); 

idc.insertAfter ("id", "00000000"); 

idc.destroy(); 

// --- --return; 

} 

/** 

* == COMPLEX SIGNATURES == 

* The getAccount service. This service takes a single string 

* "id", and returns a complex structure representing the 

* account information. Note the use of the helper functions 

* (defined below). 

*/ 

public static void getAccount (IData pipeline) 


{ 

// --- --- 

// [i] field:0:required id 

// [o] record:1:required account 

// [o] - field:0:required name 

// [o] - field:1:required refs 

// [o] - record:0:required contact 

// [o] -- field:0:required address 


} 

E. jcode tags 

// [o] -- field:0:required phone 

IDataCursor idc = pipeline.getCursor(); 

if(idc.first("id")) 

{ 

try 

{ 

String id = IDataUtil.getString(idc); 

IData data = getAccountInformation(id); 

idc.last(); 

idc.insertAfter ("account", data); 

} 

catch (Exception e) 

{ 

throw new ServiceException(e.toString()); 

} 

} 

idc.destroy(); 

// --- --- 

} 

/** 

* == SHARED SOURCE == 

* This is where the shared code lives. This includes both 

* global data structures and non-public functions that aren't 

* exposed as Services. Note the tags delimiting the start 

* and end of the shared code section. 

*/ 

// --- --private 

static Vector accounts = new Vector(); 

private static IData getAccountInformation (String id) { 

throw new RuntimeException ("this service is not implemented yet"); 

} 

// --- --- 


E. jcode tags 


Appendix F. Validation Content Constraints 

� Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

� Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

� Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 


Overview 

Content Types 

F. Validation Content Constraints 

You can apply content constraints to variables in the IS document types, specifications, or 

service signatures that you want to use as blueprints in data validation. Content 

constraints describe the data a variable can contain. At validation time, if the variable 

value does not conform to the content constraints applied to the variable, the validation 

engine considers the value to be invalid. For more information about validation, see 

Chapter 10, “Performing Data Validation”. 

When applying content constraints to variables, you can do the following: 

� Select a content type. A content type specifies the type of data for the variable value, 

such as string, integer, boolean, or date. A content type corresponds to a simple type 

definition in a schema. 

� Set constraining facets. Constraining facets restrict the content type, which in turn, 

restrict the value of the variable to which the content type is applied. Each content 

type has a set of constraining facets. For example, you can set a length restriction for a 

string content type, or a maximum value restriction for an integer content type. 

For example, for a String variable named itemQuantity, you might specify a content type 

that requires the variable value to be an integer. You could then set constraining facets that 

limit the content of itemQuantity to a value between 1 and 100. 

The content types and constraining facets described in this appendix correspond to the 

built-in data types and constraining facets in XML Schema. The World Wide Web 

Consortium (W3C) defines the built-in data types and constraining facets in the 

specification XML Schema Part 2: Datatypes (http://www.w3c.org/TR/xmlschema-2). 

The following table identifies the content types you can apply to String, String list, or 

String table variables. Each of these content types corresponds to a built-in simple type 

defined in the specification XML Schema Part 2: Datatypes. 

Note: For details about constraints for Objects and Object lists, see Appendix C, 

“Supported Data Types”. 


Content Types Description 


anyURI A Uniform Resource Identifier Reference. The value of anyURI 

may be absolute or relative. 

Constraining Facets 

enumeration, length, maxLength, minLength, pattern 

Note: The anyURI type indicates that the variable value plays the 

role of a URI and is defined like a URI. webMethods Integration 

Server does not validate URI references because it is impractical 

for applications to check the validity of a URI reference. 

base64Binary Base64-encoded binary data. 



boolean True or false. 


pattern 

Example 

true, 1, false, 0 

byte A whole number whose value is greater than or equal to –128 

but less than or equal to 127. 


enumeration, fractionDigits, maxExclusive, maxInclusive, 

minExclusive, minInclusive, pattern, totalDigits 

Example 

-128, -26, 0, 15, 125 

date A calendar date from the Gregorian calendar. Values need to 

match the following pattern: 

CCYY-MM-DD 

Where CC represents the century, YY the year, MM the month, 

DD the day. The pattern can include a Z at the end to indicate 

Coordinated Universal Time or to indicate the difference 

between the time zone and coordinated universal time. 


enumeration, maxExclusive, maxInclusive, minExclusive, 

minInclusive, pattern 

Example 

1997-08-09 (August 9, 1997) 




dateTime A specific instant of time (a date and time of day). Values need to 

match the following pattern: 

CCYY-MM-DDThh:mm:ss.sss 

Where CC represents the century, YY the year, MM the month, 

DD the day, T the date/time separator, hh the hour, mm the 

minutes, and ss the seconds. The pattern can include a Z at the 

end to indicate Coordinated Universal Time or to indicate the 

difference between the time zone and coordinated universal 

time. 




Example 

2000-06-29T17:30:00-05:00 represents 5:30 pm Eastern 

Standard time on June 29, 2000. (Eastern Standard Time is 5 

hours behind Coordinated Universal Time.) 

decimal A number with an optional decimal point. 




Example 

8.01, 290, -47.24 

double Double-precision 64-bit floating point type. 




Example 

6.02E23, 3.14, -26, 1.25e-2 




duration A length of time. Values need to match the following pattern: 

PnYnMnDTnHnMnS 

Where nY represents the number of years, nM the number of 

months, nD the number of days, T separates the date and time, 

nH the number of hours, nM the number of minutes and nS the 

number of seconds. Precede the duration with a minus (-) sign to 

indicate a negative duration. 




Example 

P2Y10M20DT5H50M represents a duration of 2 years, 10 months, 

20 days, 5 hours, and 50 minutes 

ENTITIES Sequence of whitespace-separated ENTITY values declared in 

the DTD. Represents the ENTITIES attribute type from the XML 

1.0 Recommendation. 


enumeration, length, maxLength, minLength 

ENTITY Name associated with an unparsed entity of the DTD. 

Represents the ENTITY attribute type from the XML 1.0 

Recommendation. 


enumeration, length, maxLength, minLength, pattern, 

whiteSpace 

float A number with a fractional part. 




Example 

8.01, 25, 6.02E23, -5.5 




gDay A specific day that recurs every month. Values must match the 

following pattern: 

---DD 

Where DD represents the day. The pattern can include a Z at the 

end to indicate Coordinated Universal Time or to indicate the 

difference between the time zone and coordinated universal 

time. 




Example 

---24 indicates the 24 th of each month 

gMonth A Gregorian month that occurs every year. Values must match 

the following pattern: 

--MM 

Where MM represents the month. The pattern can include a Z at 

the end to indicate Coordinated Universal Time or to indicate 

the difference between the time zone and coordinated universal 

time. 




Example 

--11 represents November 

gMonthDay A specific day and month that recurs every year in the Gregorian 

calendar. Values must match the following pattern: 

--MM-DD 

Where MM represents the month and DD represents the day. 

The pattern can include a Z at the end to indicate Coordinated 

Universal Time or to indicate the difference between the time 

zone and coordinated universal time. 




Example 

--09-24 represents September 24 th 




gYear A specific year in the Gregorian calendar. Values must match the 


CCYY 

Where CC represents the century, and YY the year. The pattern 

can include a Z at the end to indicate Coordinated Universal 

Time or to indicate the difference between the time zone and 

coordinated universal time. 




Example 

2001 indicates 2001 

gYearMonth A specific month and year in the Gregorian calendar. Values 

must match the following pattern: 

CCYY-MM 

Where CC represents the century, YY the year, and MM the 

month. The pattern can include a Z at the end to indicate 






Example 

2001-04 indicates April 2001 

hexBinary Hex-encoded binary data. 



ID A name that uniquely identifies an individual element in an 

instance document. The value for ID needs to be a valid XML 

name. The ID datatype represents the ID attribute type from the 

XML 1.0 Recommendation. 



whiteSpace 




IDREF A reference to an element with a unique ID. The value of IDREF 

is the same as the ID value. The IDREF datatype represents the 

IDREF attribute type from the XML 1.0 Recommendation. 



whiteSpace 

IDREFS Sequence of white space separated IDREFs used in an XML 

document. The IDREFS datatype represents the IDREFS 

attribute type from the XML 1.0 Recommendation. 



int A whole number with a value greater than or equal to 

-2147483647 but less than or equal to 2147483647. 




Example 

-21474836, -55500, 0, 33123, 4271974 

integer A positive or negative whole number. 




Example 

-2500, -5, 0, 15, 365 

language Language identifiers used to indicate the language in which the 

content is written. Natural language identifiers are defined in 

IETF RFC 1766. 



whiteSpace 

long A whole number with a value greater than or equal to 

–9223372036854775808 but less than or equal to 

9223372036854775807. 




Example -55600, -23, 0, 256, 3211569432 




Name XML names that match the Name production of XML 1.0 

(Second Edition). 



whiteSpace 

NCName Non-colonized XML names. Set of all strings that match the 

NCName production of Namespaces in XML. 



whiteSpace 

negativeInteger An integer with a value less than or equal to –1. 




Example 

-255556, -354, -3, -1 

NMTOKEN Any mixture of name characters. Represents the NMTOKEN 




whiteSpace 

NMTOKENS Sequences of NMTOKENS. Represents the NMTOKENS 




nonNegativeInteger An integer with a value greater than or equal to 0. 




Example 

0, 15, 32123 



nonPositiveInteger An integer with a value less than or equal to 0. 




minExclusive, minInclusive, pattern, totalDigits, whiteSpace 

Example 

-256453, -357, -1, 0 

normalizedString Represents white space normalized strings. Set of strings 

(sequence of UCS characters) that do not contain the carriage 

return (#xD), line feed (#xA), or tab (#x9) characters. 



whiteSpace 

Example 

MAB-0907 

positiveInteger An integer with a value greater than or equal to 1. 




Example 

1, 1500, 23000 

short A whole number with a value greater than or equal to -32768 but 

less than or equal to 32767. 




Example 

-32000, -543, 0, 456, 3265 

string Character strings in XML. A sequence of UCS characters (ISO 

10646 and Unicode). By default, all white space is preserved for 

variables with a string content constraint. 



whiteSpace 

Example 

MAB-0907 




time An instant of time that occurs every day. Values must match the 


hh:mm:ss.sss 

Where hh indicates the hour, mm the minutes, and ss the 

seconds. The pattern can include a Z at the end to indicate 






Example 

18:10:00-05:00 (6:10 pm, Eastern Standard Time) Eastern 

Standard Time is 5 hours behind Coordinated Universal Time. 

token Represents tokenized strings. Set of strings that do not contain 

the carriage return (#xD), line feed (#xA), or tab (#x9) characters, 

leading or trailing spaces (#x20), or sequences of two or more 

spaces. 



whiteSpace 

unsignedByte A whole number greater than or equal to 0, but less than or equal 

to 255. 




Example 

0, 112, 200 

unsignedInt A whole number greater than or equal to 0, but less than or equal 

to 4294967295. 




Example 

0, 22335, 123223333 





unsignedLong A whole number greater than or equal to 0, but less than or equal 

to 18446744073709551615. 




Example 

0, 2001, 3363124 

unsignedShort A whole number greater then or equal to 0, but less than or equal 

to 65535. 




Example 

0, 1000, 65000 

When you apply a content type to a variable, you can also set constraining facets for the 

content type. Constraining facets are properties that further define the content type. For 

example, you can set a minimum value or precision value for a decimal content type. Each 

content type has a set of constraining facets. The constraining facets described in the 

following table correspond to constraining facets defined in the specification XML Schema 

Part 2: Datatypes. 

Constraining Facet Description Usage Notes 

enumeration The possible values for the variable 

at run time. 

fractionDigits The maximum number of digits to 

the right of the decimal point. For 

example, the fractionDigits of the 

value 999.99 is 2. 

If you also entered possible 

values using the Pick list 

choices property in the General 

category of the Properties 

panel, those values will be 

displayed at run time. 

However, the enumeration 

values will be used for 

validation. 

fractionDigits must be less than 

or equal to totalDigits. 



length The precise units of length 

required for the variable value. 

maxExclusive The upper bound of a range of 

possible values. The range 

excludes the value you specify. The 

variable can have a value less than 

but not equal to maxExclusive. 

maxInclusive The upper bound of a range of 


includes the value you specify. The 

variable can have a value less than 

or equal to maxInclusive. 

maxLength The maximum units of length 

permitted for the variable value. 

minExclusive The lower bound of a range of 

possible values. The range does 

not include the value you specify. 

The variable can have a value 

greater than but not equal to 

minExclusive. 

minInclusive The lower bound of a range of 


includes the value you specify. The 

variable can have a value greater 

than or equal to minInclusive. 

minLength The minimum units of length 

permitted for the variable value. 

pattern A pattern (regular expression) that 

the value of the variable must 

match. For example, you can use a 

regular expression to specify that a 

variable that is a string content 

constraint match a Social Security 

number format. 


If you specify length, you 

cannot specify either 

minLength or maxLength. 

maxExclusive must be greater 

than or equal to minExclusive. 

You cannot specify 

maxInclusive and maxExclusive 

for the same content type. 

maxInclusive must be greater 

than or equal to minInclusive. 


maxInclusive and maxExclusive 


maxLength must be greater 

than or equal to minLength. 

minExclusive must be less than 

or equal to maxExclusive. 


minInclusive and minExclusive 


minInclusive must be less than 

or equal to maxInclusive. 


minInclusive and minExclusive 


minLength must be less than or 

equal to maxLength. 



totalDigits The maximum number of decimal 

digits allowed in a value. For 

example, the totalDigits of the value 

999.99 is 5. 

whiteSpace The white space normalization 

performed on the variable value. 

The value of whiteSpace can be one 


preserve: No white space 

normalization is performed. 

replace: Carriage returns (#xD), 

line feeds (#xA), and tabs (#x9) are 

replaced with a single space (#x20). 

collapse: After the white space 

normalization specified by replace 

is performed, sequences of spaces 

(#x20) and leading and trailing 

spaces (#x20) are removed. 


totalDigits must be greater 

than or equal to fractionDigits. 

Note: Previous versions of XML Schema contained the constraining facets duration, 

encoding, period, precision, and scale. However, these constraining facets are not included in 

the recommendation of XML Schema Part 2: Datatypes. The constraining facets duration, 

encoding, and period were removed. precision was renamed totalDigits. scale was renamed 

fractionDigits. If you view a content type from an IS schema created from an XML Schema 

Definition that used pre-Recommendation version of XML Schema (before May 2001) the 

Content Type dialog box will display the constraining facets that were available in the 

pre-Recommendation version of XML Schema. 

Note: The word “fixed” appears next to the name of a constraining facet whose value is 

fixed and cannot be changed. When a facet has a fixed value, the facet is called a fixed 

facet. 


Appendix G. Validation Errors and Exceptions 

� Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 

� Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 

� Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 

� IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 


Overview 

Validation Errors 

G. Validation Errors and Exceptions 

This appendix describes error messages that can occur during data validation, IS schema 

generation, or IS document type generation. 

When the validation engine in the webMethods Integration Server validates an object (an 

XML node, the pipeline, or documents) and the object does not conform to the blueprint 

or model, the server generates errors and/or exceptions. You might also receive errors and 

exceptions when creating an IS schema. The following sections describe the errors and 

exceptions you can receive when performing validation and when creating an IS schema. 

When you perform validation using a built-in service, webMethods Integration Server 

returns validation errors in the errors output variable if the object is invalid. When you 

perform input/output validation, webMethods Integration Server throws an exception if 

the inputs or outputs are invalid. Error messages are contained in the exception. 

Each validation error contains a code and a default message. Error code prefixes indicate 

the validation error type: 

� DT indicates a data type validation error. Data type validation errors pertain to the 

content type constraints applied to the variables. 

� NV indicates a node validation error. Node validation errors pertain to the validation 

of an XML node. 

� VV indicates a document validation error. Document validation errors pertain to the 

structure of the data values (for example, an invalid document structure). 

The following table describes the validation errors you can receive when performing 

XML, pipeline, or document validation. 

Error Code Message and Description 

DT-001 

DT-002 

[ISC.0082.9447] Value does not conform to datatype. 

Cause: The value does not match the specified content 

type. 

[ISC.0082.9460] No matching enumeration value. 

Cause: The value is not an item listed in the enumeration 

field. 



DT-003 

DT-004 

DT-005 

DT-006 

DT-007 

DT-008 

DT-009 

DT-010 


[ISC.0082.9463] Length of value is not equal to specified length. 

Cause: The size of the value does not equal the number 

specified in the length field. 

[ISC.0082.9464] Value is shorter than minimum length. 

Cause: The size of the value is less than the number 

specified in the minLength field. 

[ISC.0082.9465] Value is longer than maximum length. 

Cause: The size of the value is greater than the number 

specified in the maxLength field. 

[ISC.0082.9489] Number of digits is greater than totalDigits. 

Cause: The number of digits in the value is greater than 

the number specified in the totalDigits field. 

[ISC.0082.9490] Number of fraction digits is greater than 

fractionDigits. 

Cause: The number of digits to the right of the decimal 

point is greater than the number specified in the 

fractionDigits field. 

[ISC.0082.9491] Value is less than minInclusive. 

Cause: The value is less than the value specified in the 

minInclusive field. 

[ISC.0082.9492] Value is less than or equal to minExclusive. 

Cause: The value is less than or equal to the value 

specified in the minExclusive field. 

[ISC.0082.9493] Value is greater than maxInclusive. 

Cause: The value is greater than the value specified in the 

maxInclusive field. 



DT-011 

DT-012 

DT-013 

DT-Binary001 

DT-Binary002 

DT-Binary003 

DT-Binary004 

DT-Boolean001 

DT-Decimal001 


[ISC.0082.9494] Value is greater than or equal to maxExclusive. 

Cause: The value is greater than or equal to the value 

specified in the maxExclusive field. 

[ISC.0082.9448] Value does not match pattern. 

Cause: The value does not match the pattern specified in 

the pattern field. 

[ISC.0082.9474] The input has invalid characters. 

Cause: The specified whiteSpace value is invalid. The 

value of the whiteSpace field can be preserve, replace, or 

collapse. 

[ISC.0082.9293] No matching choice value 

Cause: The binary value is not an element listed in the 

choices field. 

[ISC.0082.9297] Value is shorter than minimum length 

Cause: Size of the binary value, in octets, is less than the 

value specified in the minimum length field. 

[ISC.0082.9298] Value is longer than maximum length 

Cause: Size of the binary value, in octets, is greater than 

the value specified in the maximum length field. 

[ISC.0082.9296] Length of value is not equal to specified length 

Cause: Size of the binary value, in octets, is not equal to the 

value specified in the length field. 

[ISC.0082.9246] Value does not conform to datatype 

Cause: The value is not a Boolean. 


Cause: The decimal value is not an element listed in the 




DT-Decimal002 

DT-Decimal003 

DT-Decimal004 

DT-Decimal005 

DT-Decimal006 

DT-Double001 

DT-Double002 

DT-Double003 

DT-Double004 



Cause: The value is not a parsable decimal. 

[ISC.0082.9294] Value is less than minimum 

Cause: The decimal value is less than the value specified in 

the minimum exclusive or minimum inclusive field. 

[ISC.0082.9295] Value is greater than maximum 

Cause: The decimal value is greater than the value 

specified in the maximum exclusive or maximum inclusive 

field. 

[ISC.0082.9300] Value exceeds precision 

Cause: The total number of digits in the decimal value is 

greater than the value specified in the precision field. 

[ISC.0082.9301] Value exceeds scale 

Cause: The total number of digits to the right of the 

decimal point is greater than the value specified in the 

scale field. 


Cause: The double value is not an element listed in the 



Cause: The double value is less than the value specified in 



Cause: The double value is greater than the value specified 

in the maximum exclusive or maximum inclusive field. 


Cause: The value is not a parsable double. 



DT-Float001 

DT-Float002 

DT-Float003 

DT-Float004 

DT-Int001 

DT-Int002 

DT-Int003 

DT-Int004 

DT-INTEGER001 



Cause: The float value is not an element listed in the 



Cause: The float value is less than the value specified in 



Cause: The float value is greater than the value specified in 

the maximum exclusive or maximum inclusive field. 


Cause: The value is not a parsable float. 


Cause: The integer value is not an element listed in the 



Cause: The integer value is less than the value specified in 



Cause: The integer value is greater than the value specified 



Cause: The value is not a parsable integer. 


Cause: The integer value is not an element listed in the 




DT-INTEGER002 

DT-INTEGER003 

DT-INTEGER004 

DT-Long001 

DT-Long002 

DT-Long003 

DT-Long004 

DT-List001 

DT-List002 



Cause: The value is not a parsable integer. 


Cause: The integer value is less than the value specified in 



Cause: The integer value is greater than the value specified 



Cause: The long value is not an element listed in the 



Cause: The long value is less than the value specified in the 

minimum exclusive or minimum inclusive field. 


Cause: The long value is greater than the value specified in 



Cause: The value is not a parsable long. 


Cause: The sequence of values in the list is not an element 

in the choices field. 


Cause: Size of the list is less than the value specified in the 

minimum length field. 



DT-List003 

DT-List004 

DT-RecurringDuration001 




DT-STR001 

DT-STR002 



Cause: Size of the list is greater than the value specified in 

the maximum length field. 

[ISC.0082.9299] Datatype definition is missing 

Cause: Datatype or simple type definition is not found. It 

is possible that a dependent IS schema that contains this 

datatype definition was removed from the IS Namespace. 


Cause: The recurring duration value is not an element 

listed in the choices field. 


Cause: The recurring duration value is less than the value 

specified in the minimum exclusive or minimum inclusive 

field. 


Cause: The recurring duration value is greater than the 

value specified in the maximum exclusive or maximum 

inclusive field. 


Cause: The recurring duration value does not match the 

pattern specified in the pattern field. 


Cause: The string value is not an element listed in the 



Cause: The size of the string, in characters, is less than the 

value specified in the minimum length field. 



DT-STR003 

DT-STR004 

DT-Time001 

DT-Time002 

DT-Time003 

DT-Time004 

DT-TimeDuration001 




Cause: The size of the string, in characters, is greater than 

the value specified in the maximum length field. 

[ISC.0082.9307] Does not match pattern(s) 

Cause: The string value does not match the pattern 

specified in the pattern field. 


Cause: The time value is not an element listed in the 



Cause: The time value is less than the value specified in the 

minimum exclusive or minimum inclusive field. 


Cause: The time value is greater than the value specified in 



Cause: The time value does not match the pattern 



Cause: The time duration value is not an element listed in 

the choices field. 


Cause: The time duration value is less than the value 


field. 





DT-TimePeriod001 




NV-001 

NV-002 



Cause: The time duration value is greater than the value 


field. 


Cause: The time duration value does not match the pattern 


[ISC.0082.9246] Values does not conform to data type 

Cause: The time period value does not match data type 

specified in the IS schema. 


Cause: The time period value is not an element listed in 

the choices field. 


Cause: The time duration value is less than the value 


field. 


Cause: The time duration value is greater than the value 


field. 

[ISC.0082.9001] Error while parsing 

Cause: The XML document cannot be parsed. It is possible 

that the XML document being validated is not well 

formed. 

[ISC.0082.9002] Unable to retrieve root element 

Cause: XML document is empty. 

Response: Check that the document is being submitted 

properly. 



NV-003 

NV-004 

NV-005 

NV-006 

NV-007 


[ISC.0082.9003] Unable to locate a matching element declaration 

Cause: An undeclared element node is found in the 

instance document. 

Response: Check to make sure that the document uses 

only declared elements. 

[ISC.0082.9004] [attributes] property must be empty 

Cause: This element carries attributes that are not 

expected. 

Response: Check to make sure that the document only 

uses element attributes that are declared in the schema. 

[ISC.0082.9005] Element information items are not allowed in 

[children] property 

Cause: This element contains child elements; however, the 

element declaration in the IS schema indicates that the 

element does not contain any child elements. 

Response: Check to make sure that the document properly 

conforms to the schema. 

[ISC.0082.9006] Unable to locate a matching attribute declaration 

Cause: This element carries an attribute that is not 

declared in the element declaration in the IS schema. 

Response: Check to make sure that the document only 

uses element attributes that are declared in the schema. 

[ISC.0082.9007] Missing Attribute Information Item 

Cause: A required attribute is not found in this element 

node. 

Response: Check to make sure that the document 




NV-008 

NV-009 

NV-010 


[ISC.0082.9008] Invalid value - does not match fixed value 

Cause: The instance document contains an invalid element 

body or attribute value. Specifically, the element body or 

attribute value does not match a fixed value found in the 

declaration. 



[ISC.0082.9009] Child element elementName at position location 

is unexpected. 

Cause: The element is not a valid child element or the 

sequence of child elements does not satisfy the order 

specified in the corresponding element declaration or 

complex type definition. 



[ISC.0082.9010] Incomplete content–one or more child elements 

are expected. 

Cause: The element is not a valid child element or the 

sequence of child elements does not satisfy the order 

specified in the definition. 



[ISC.0082.9011] Unable to locate attribute declaration 

Cause: An attribute declaration is not found. It is possible 

that a dependent IS schema that contains this attribute 

declaration was removed from the IS Namespace. For 

example, IS schema pub.schema.w3c:datatypes references an 

attribute declaration (xml:lang) in pub.schema.w3c:xml . If 

you receive this error, it is possible that pub.schema.w3c:xml 

was removed. 

Response: Check to make sure that all of the attribute 

declarations referenced by the schema are present. 



NV-011 

NV-012 

NV-013 

NV-014 

[ISC.0082.9012] Unable to locate type definition 


Cause: A simple or complex type definition is not found. It 

is possible that a dependent IS schema that contains this 

type definition was removed from the IS Namespace. For 

example, IS schema pub.schema.w3c:structures references a 

type definition in pub.schema.w3c:datatypes. If you receive 

this error, it is possible that pub.schema.w3c:datatypes was 

removed. 

Response: Check to make sure that all of the type 

definitions referenced by the schema are present. 

[ISC.0082.9014] Unable to locate element declaration 

Cause: An element declaration is not found. It is possible 

that a dependent IS schema that contains the element 

declaration was removed from the IS Namespace. 

Response: Check to make sure that all the element 

declarations referenced by the schema are present. 

[ISC.0082.9016] Unable to resolve QName: localName:{uri} 

Cause: The schema processor uses the namespaces 

declared in the instance document to resolve a QName to: 

{Namespace URI} Local Name 

However, the schema processor is unable to resolve the 

QName using the namespace declarations in the instance 

document. 



[ISC.0082.9017] typeName is not validly derived from 

declaredTypeName 

Cause: This error occurs when the first type is used in a 

context where the second type is expected, and either the 

first type is not the same as the second type or the first 

type is not validly derived from the second type. 

Response: Check to make sure that the correct types are 

specified in the schema and that the correct 

corresponding types are used in the document. 



NV-015 

NV-016 

NV-017 

NV-018 


[ISC.0082.9018] typeName is an abstract type and cannot be used 

directly to validate content 

Cause: The specified type is an abstract type that has been 

either declared or nominated. Abstract types cannot be 

used to validate element content. 

Response: Make sure to use only concrete types when 

validating element content. 

[ISC.0082.9019] elementName is an abstract element and cannot 

appear in an instance 

Cause: The element declaration identifies the element as 

an abstract element. Abstract elements cannot appear in 

instance documents. 

Response: Make sure to only use concrete elements in 

instance documents. 

[ISC.0082.9020] QName - xsi:type is used incorrectly (declared 

type is anonymous) 

Cause: A type is nominated using xsi:type for an element 

whose declaration contains an anonymous type. A new 

type cannot be derived from an anonymous type because 

new types can be derived only from named types. 

Response: Be sure to use only named types when 

declaring new types. 

[ISC.0082.9021] Contains invalid text 

Cause: The schema processor encountered an invalid piece 

of text. It is possible that the instance document contains a 

simple type where element declarations are interspersed 

with text. Simple types cannot contain element 

declarations. 





VV-001 

[ISC.0082.9025] Missing Object 


Cause: A required document (IData object) or variable is 

missing from the input. 

Response: Be sure that the arguments are being passed 

properly to the validator. 

VV-002 [ISC.0082.9026] Undefined Object found 

VV-003 

Cause: A document (IData object) contains an orphan 

variable. (This message only appears if the Allow 

unspecified fields property in the Constraints category of the 

Properties panel is False.) 

Response: Make sure that all variables are defined, or 

check the box to allow unspecified fields on the 

constraints tab of the Variable Properties dialog box. 

[ISC.0082.9027] Dimension mismatch, List expected 

Cause: The value being validated is a scalar value or a 

multi-dimensional array (String table), however the 

variable it is being validated against is a list (onedimensional 

array). 



[ISC.0082.9028] Dimension mismatch, Single item expected 

Cause: The value being validated is an array value (a list or 

a table). The variable it is being validated against is scalar. 



[ISC.0082.9029] Dimension mismatch, Table expected 

Cause: The value being validated is a scalar value or a onedimensional 

array (list). The variable it is being validated 

against is a two-dimensional array (table). 




Validation Exceptions 


VV-004 

[ISC.0082.9030] Type mismatch, String expected 


Cause: The value is being validated against a String 

variable, but the IS data type of the value is not a String. 



[ISC.0082.9031] Type mismatch, Document expected 

Cause: The value is being validated against an IS 

document type variable, but the IS data type of the value 

is not an IS document type. 



[ISC.0082.9032] Type mismatch, Object expected 

Cause: The value is being validated against an Object 

variable, but the IS data type of the value is not an Object. 



At run time, the service performing validation either succeeds or fails. If the service fails, 

webMethods Integration Server throws a validation exception. A validation exception is 

generated if one of the following is true: 

� Errors are detected in the object (XML node, pipeline, or document (IData object)) that 

is passed (for example, null value). 

� The basic validation contract is violated (for example, a binary tree is passed instead 

of a document (IData object) as expected). 

� You specify that the service should fail if the object to be validated (XML node, 

pipeline, or document (IData object)) did not conform to the IS schema or IS 

document type (for example, failIfInvalid = true). If this is the reason for the exception, 

webMethods Integration Server inserts the validation errors into the exception 

message. 



The following table identifies and describes the validation exceptions that can be 

generated. 

Default Exception Message When is it thrown? Description 

[ISS.0062.9021] object is null 

[ISS.0062.9022] %NSName% - 

object does not exists 

[ISS.0062.9024] webMethods 

Integration Server does not 

support this type of validation 

(may or may not support in 

the future) 

[ISS.0062.9202] Invalid: 

minLength 


maxLength 

[ISS.0062.9211] Invalid 

Regular Expression: 

Expression 

Real time and 

design time 

Real time and 

design time 

Real time and 

design time 

Cause: The object to be validated does 

not exist in the pipeline. 

Response: Link an XML node or 

document variable to the object 

variable in Service In. 

Cause: The IS document type or IS 

schema specified for the conformsTo 

variable does not exist in the IS 

Namespace. 

Response: Change the value of 

conformsTo to be an IS document type 

or IS schema that exists in the IS 

namespace. 

Cause: The object to be validated is not 

one of the types supported by 

validation. 

Response: Currently, only XML, 

pipeline, and document (IData object) 

validation is supported. 

Design time Cause: The min length is either not a 

parsable number or conflicts with max 

length. 

Response: Change the min length value 

and make sure that it is within the 

allowed range for the content type. 

Design time Cause: The max length is either not a 

parsable number or conflicts with 

minimum length. 

Response: Change the max length value 

and make sure that it is within the 

allowed range for the content type. 

Design time Cause: The pattern is an invalid Perl 

regular expression. 

Response: Modify the pattern and 

make sure that it is Perl regular 

expression. 




minInclusive 


minExclusive 


maxInclusive 


maxExclusive 

[ISS.0062.9230] Invalid scale 


Design time Cause: The specified minInclusive value 

is invalid. For example, the 

minInclusive value for a variable with 

content type constraint of short must 

also be a short. 

Response: Make sure the minInclusive is 

a valid number for the specified 

content type. 

Design time Cause: The specified minExclusive 

value is invalid. For example, the 

minExclusive value for a variable with 



Response: Make sure the minExclusive 

is a valid number for the specified 

content type. 

Design time Cause: The specified maxInclusive value 

is invalid. For example, the 

maxInclusive value for a variable with 



Response: Make sure the maxInclusive 


content type. 

Design time Cause: The specified maxExclusive 

value is invalid. For example, the 

maxExclusive value for a variable with 



Response: Make sure the maxExclusive 


content type. 

Design time Cause: The value of a constraining 

facet has an invalid scale. 

Response: Examine the constraining 

facet values to make sure the values 

do not conflict. 



[ISS.0062.9231] Exceeds 

precision: minInclusive 


precision: minExclusive 


precision: maxInclusive 


precision: maxExclusive 

[ISS.0062.9235] Invalid 

enumerated item 


Design time Cause: The value of the minInclusive 

constraining facet exceeds the value 

specified for totalDigits. 


minInclusive or totalDigits to make sure 

the values do not conflict. 

Design time Cause: The value of the minExclusive 




minExclusive or totalDigits to make sure 


Design time Cause: The value of the maxInclusive 




maxInclusive or totalDigits to make sure 


Design time Cause: The value of the maxExclusive 




maxExclusive or totalDigits to make sure 


Design time Cause: A content type constraint is 

defined in terms of the collective set 

of constraining facet values. Together, 

these values determine the allowed 

values and properties of the content 

type. The constraining facet value you 

just specified may conflict with other 

constraining facet values. For 

example, if you specify length for the 

string content type, you cannot 

specify min length or max length. 

Response: Examine the constraining 

facet values to make sure the values 

do not conflict with each other. 



[ISS.0062.9302] Maximum is 

less than minimum 

[ISS.0062.9303] Minimum is 

out of range (Valid range is 

from lowerBound to 

upperBound) 

[ISS.0062.9304] Maximum is 

out of range (Valid range is 

from lowerBound to 

upperBound) 

IS Schema Generation Errors and Warnings 


Design time Cause: Invalid condition. The 

maximum value is less than the 

minimum value. 

(maximum < minimum) 

Response: Change the maximum or 

minimum value to eliminate the 

conflict. 

Design time Cause: The minimum value is out of 

the valid range for the content type. 

Response: Change the minimum value 

(min exclusive, min inclusive, or min 

length) and make sure that it is within 

the allowed range for the content 

type. 

Design time Cause: The specified maximum value 

is out of the valid range for the 

content type. 

Response: Change the maximum 

value (max exclusive, max inclusive or 

max length) and make sure that it is 

within the allowed range for the 

content type. 

When you create an IS schema from a DTD or an XML Schema definition, you may receive 

errors or warnings. The following table identifies and describes the errors you might 

receive when creating an IS schema. Error or warning codes that begin with DTDC are 

errors that occur when you generate an IS schema from a DTD (or from an XML 

document that references an existing DTD). Error or warning codes that begin with XSDC 

are errors that occur when you generate an IS schema from an XML Schema definition. 

Note: You might also receive these errors and warnings when you generate an IS document 

type or flow service from an XML Schema definition, DTD, or XML document that 

references a DTD. For more information about creating an IS document type, see 

“Creating an IS Document Type” on page 244. For more information about creating a flow 

service, see “Creating a New Flow Service” on page 127. 


Code Message and Description 

CONV-001 

DTDC-001 

DTDC-002 

DTDC-003 

DTDC-005 

XSDC-001 

XSDC-002 

[ISC.0082.9101] Document type generation error: errorNumber. 


Cause: The schema processor encountered an error in the XML Schema 

definition used to create an IS document type. 

Response: Contact webMethods Technical Services. 

[ISC.0082.9501] DTD is empty 

Cause: The DTD does not contain any information. 

Response: Make sure that the DTD is valid. 

[ISC.0082.9502] NS Declaration is missing for prefix 'prefixName' 

Cause: Warns that an XML Namespace prefix is used without declaring 

it. 

Response: Declare the XML Namespace prefix before using it. 

[ISC.0082.9503] Error while parsing' 

Cause: Warns that a DTD cannot be parsed. It is possible the DTD does 

not satisfy XML 1.0. 

[ISC.0082.9505] Name collision detailedWarningMessage 

Cause: Warns that an element type declaration is found in another 

schema with the same XML Namespace. 

Response: Use a different XML Namespace. 

[ISC.0082.9703] Duplicate declaration found in this schema definition 

Cause: A duplicate attribute or element declaration is found in the XML 

Schema definition. 

Response: Make sure the XML Schema definition is valid. 

[ISC.0082.9704] Duplicate definition found in this schema definition 

Cause: A duplicate simple type or complex type definition is found in 

the XML Schema definition. 

Response: Make sure the XML Schema definition is valid. 



XSDC-003 

XSDC-004 

XSDC-005 

XSDC-006 

[ISC.0082.9705] Definition not found 


Cause: A simple type or complex type definition is missing from the 

XML Schema definition. 

Response: Make sure the datatype definition is present in the XML 


[ISC.0082.9706] Declaration not found 

Cause: An error. An element declaration or attribute declaration is 

missing from the XML Schema definition. 

[ISC.0082.9707] Base type definition not found 

Cause: A base type definition that is used to derive either a simple type 

or complex type is missing from the XML Schema definition. 

Response: Make sure the base type definition is present in the XML 


[ISC.0082.9708] Type derivation not OK 

Cause: An error. As per the spec (s) from the W3C, the “type derivation is 

not OK.” 

[ISC.0082.9709] Type derivation not OK: attribute declaration to be restricted is 

not found in the base type definition 

Cause: In a complex type derivation, an attribute declaration restricts the 

use of an attribute. However, this attribute declaration is not found in 

the base type definition. 

Response: Make sure that the attribute declaration is present in the base 

type definition. 

[ISC.0082.9710] Type derivation not OK: attribute declaration to be prohibited is 

not found in the base type definition 

Cause: In a complex type derivation, an attribute declaration prohibits 

the use of an attribute. However, this attribute declaration is not found 

in the base type definition. 

Response: Make sure that the attribute declaration is present in the base 

type definition. 



XSDC-008 

XSDC-009 

XSDC-080 

XSDC-081 


[ISC.0082.9712] Incorrect facet (s) specified: typeName throws errorMessage. 

Cause: Constraining facets applied to the data type are incorrect or 

cannot be used with the data type. 

Response: Use the error messages to determine which constraining facets 

to remove from the type definition. 

[ISC.0082.9713] Unable to resolve QName 

Cause: Incorrect QName. 

Response: Check the value of the QName. 

[ISC.0082.9701] Duplicate declaration found in this schema 

folderName:schemaNamewith the same target namespace 

Cause: Warns that an identical attribute declaration or element 

declaration is found in the specified schema with the same target 

namespace. The schema processor creates the schema but does not 

include the duplicate declaration. Instead, the schema contains a pointer 

to the first (original) declaration. 

Response: None required. 

[ISC.0082.9702] Duplicate definition found in this schema 

folderName:schemaName with the same target namespace 

Cause: Warns that an identical simple type or complex type definition is 

found in the specified schema with the same target namespace. The 

schema processor creates the schema but does not include the duplicate 

type definition. Instead, the schema contains a pointer to the first 

(original) type definition. 

Response: None required. 

[ISC.0082.9106] Complex type TypeName is recursive. webMethods Integration 

Server does not support creating a document type from an XSD with a recursive 

complex type. 

Cause: The XML Schema contains a recursive complex type definition. 

The Integration Server does not support generating a document type 

from an IS schema containing a recursive complex type. This error only 

occurs when you generate an IS document type from an XML Schema. 

Response: Do not try to generate a document type from a schema 

containing a recursive complex type. 




Index 

Symbols 

! 439 

!= 436 

" 444 

% 444 

& 440 

&& 440 

( 444 

) 444 

/ 444 

< 436 

436 

>= 436 

\ 444 

_env field 251 

| 439 

|| 439 

‡ 265 

A 

access control 110 

ACLs 

assigning to elements 110, 113 

assigning to packages and folders 113 

checking for services 111 

defined 110 

element creation, view, and deletion implications 118 

inheritance 115 

locking implications 117 

requirements for using Developer 20 

testing and debugging implications 118 

viewing on a server 116 

actions, performing on IS elements 34 

adapter notifications 

described 252 

guidelines for moving and copying 53 

adapter services, retry behavior 390 

adding 

folders 127 

packages 76 

transformers 224 

variables to pipeline link 221 

addressing 

variables in expressions and filters 441 

variables with special characters 443 

alarm events 

building handlers for 373 

definition of 362, 372 

reasons generated 372 

uses of 373 

all content model 237 

Allow unspecified fields option 262 

and operator 440 

annotating source code for jcode 329 

anonymous type definitions 237 

any attribute declaration 236 

any element declaration 236 

anyURI content constraint 455 

API for Java services 323, 328 

applying 

conditions to links 214 

constraints to variables 261, 454 

areas of Developer window 

behavior and operation 33 

editor 30 

focus 33 

general layout 23 

Navigation panel 24 

Properties panel 31 

Recent Elements tab 29 

resizing 35 

Results panel 33 

Servicenet tab 28 

switching perspectives 36 


Index

zooming 35 

arithmetic services 224 

array variables 

default behavior for linking 424 

definition of 424 

guidelines for linking 213 

linking to or from array variables 211, 424 

linking to or from scalar variables 211, 424 

linking to transformers 228 

using in filters 446 

assigning 

default value to a variable 217 

replication services 90 

shutdown services 90 

startup services 90 

universal names to services 145 

values to pipeline variables 216, 217 

variable values to a variable 218 

version numbers to packages 83 

attribute 

declaration 236 

reference 236 

audit data, when generated 149 

audit events 



when generated 150 

Audit level property 156 

audit log 

configuring 148 

described 149 

auditing 


failed and successful services 150, 154 

failed services 150 

for errors 153 

for recovery, described 155 

for resubmission purposes 153 

long-running services 155 

service retry 143 

services 148 

use cases 153 

auditing options 

overwritten by server property 156 

setting for a service 155 

auditLog server property 156 


B 

base64Binary content constraint 455 

binding options for COM objects 339 

blank labels in BRANCH steps 173 

blue links, in the Pipeline tab 212 

booleans 

content constraint 455 

in filters, Broker restrictions 445 

BRANCH step 

branching on empty values 172 

branching on expressions 171 

branching on null values 172 

branching on switch value 169 

creating 177 

creating a multi-step child for 175 


Evaluate labels property 171 

specifying default step 174 

specifying label value 170 

specifying switch variable 170 

switch value 169 

using conditional expressions 171 

using in a flow 168 

using SEQUENCE as a target of 175 

using with regular expressions 170 

breakpoints 

and the Trace Into command 296 

clearing from flow steps 296 

clearing from transformers 297 

listing all 298 

locating in flow services 298 

overview 295 

point when processing halts 296, 297 

removing 298 

setting in flow services 296 

setting on a flow step 296 

setting on a transformer 297 

Index

Broker 

filter collation locale 437 

filter rules 444 

Broker document type, creating publishable document type from 

248 

browser clients 

creating 356 

invoking services from 357, 359 

testing from 286 

building 

event handler sample 371 

event handlers 370 

flow services 122 

built-in services 

for arithmetic operations 224 

for date/time transformations 224 

for document (IData object) validation 269 

for pipeline validation 270 

for remote services 166 

for string manipulation 224 

for XML validation 271 

invoking 166 

throwExceptionForRetry 144 

byte content constraint 455 

C 

C/C++ clients 

creating 350, 351 

creating a make file 351 

C/C++ services 

compiling with a make file 332 


caching 


elements to improve Developer performance 70 

services not suited for 139 

services suited for 139 

setting 141 

using prefetch 140 

call stack 285 

catch sequence, in service retry 391 

changing 

level of a step 162 

passwords 39 

position of a step 162 

child flows 

described 162 

stepping in/out of child flows 294 

tracing 292 

choice content model 237 

circular dependencies, between packages 87 

class files 

location of 327 

clearing 

breakpoints on flow steps 296 

breakpoints on transformers 297 

client applications 

creating browser-based 356 

creating C/C++ 350 

creating Excel 355 

creating Java 346 

creating Visual Basic 352 

closed documents, described 262 

closing a session on webMethods Integration Server 37 

coded services, about 316 

collapsing 


white space 466 

COM objects 

binding options 339 

invoking as services 337 

using with webMethods components 336 

COM services 

creating 336 

invoking 339, 341 

com.wm.app.b2b.server.ISRuntimeException class 144 

combining Trace and Step commands 289 

commands 

Disable Step 298, 299 

Enable Step 298, 299 

Load Pipeline Locally 306 

Reset 290 

Restore Pipeline from Server 306 

Restore Pipeline Locally 306 

Save Pipeline from Server 306 

Save Pipeline Locally 304 


Index

Save Pipeline to Server 304 

Set Breakpoint 296 

Step 288, 292, 293 

Step Into 288, 292, 294 

Step Out 292, 294 

Trace 288, 290, 291 

Trace Into 288, 290, 292 

Trace to Here 288, 290, 291 

comments for jcode 329 

Comments property, definition 164, 402 

compiling 

C/C++ services 336 

error in Java compiler location 324 

Java services 324, 330 

services with Developer 324 

services with jcode 330, 332 

specifying the Java compiler 324 

Visual Basic services 339 

complex type definition 

all content model 237 

anonymous 237 

choice content model 237 

described 237 

empty content 237 

mixed content 237 

sequence content model 237 

composite mode (jcode) 331 

conditional expressions 

addressing variables 441 

addressing variables with special characters 443 

lexical operators 437 

logical operators 439 

operator precedence 441 

standard relational operators 435 

syntax 431 

using with pipeline links 214 

using with the BRANCH step 171 

conditional links 

creating 216 

described 214 

disabling 301 

conditions 

applying to links 214 

disabling on links 301 

connecting to webMethods Integration Server 22, 37 

constraining facets 

applying 265 

described 261, 464 


constraints 

content 234, 454 


for IS schemas 234 


structural 234 

viewing for variables 265 

content constraints 

applying to variables 261 

constraining facets 261, 464 

editing for simple types 242 

for String variables, definition of 454 

for validation 454 

for variables, definition of 261 


in IS schemas 234 

in IS schemas, definition of 234 

content models 

all 237 

choice 237 

empty 237 

mixed 237 

sequence 237 

content types 

applying to variables 262 

constraint symbol 265 

customizing 264 

specifiying constraining facet values 265 

context-sensitive menus 34 

Control steps 

BRANCH 124, 168 


EXIT 124, 190 

LOOP 124, 186 

REPEAT 124, 179 


Index

SEQUENCE 124, 185 

conventions used in this document 17 

converting string lists to document (IData object) lists 210 

copying 

by reference, definition of 206 

by value, definition of 206 

elements from the Results panel 283 

IS elements 51 

pipeline values 219 

set values 219 


creating 

code for Java services 325 

event filters 366 

event filters for services 368 

event handler sample 371 


flow services 126, 127 

folders 127, 332 


IS schemas 239 

Java services with an IDE 329 

Java services with C/C++ 332 

Java services with Developer 319, 323 

Java services with Visual Basic 336, 339 

Java services with your own IDE 327 

links to array variables 424 

links to document (IData object) variables 208 

packages 76 

specifications for C/C++ services 332 

version numbers for packages 83 

cursors 317 

customizing content types 264 

D 

dagger symbol, next to variable icon 265 

data transformations, definition of 196 

data types 

icons to represent 129 

linking with Pipeline tab 209 

supported by webMethods Integration Server 420 

tables 423 

data validation 

allowing undeclared variables 262 

applying constraints 261 

benefits of 260 

blueprints for 260 

closed variables 262 

content constraints 261 


document (IData object) validation 269 

errors 468 

exceptions 273, 482 

input/output validation 


performing via Input/Output tab 267 

performing via INVOKE step properties 268 

open variables 262 

pipeline validation 270 

requiring variable existence 262 

structural constraints 261 

types of 260 

XML validation 271 

date content constraint 455 

date conversion services 224 

dateTime content constraint 456 

DCOM objects 

invoking as services 337 

using with webMethods Integration Server 336 

debug level, setting on server 309 

debugging flow services 

breakpoints 295 

combining trace and step 289 

disabling a single flow step 298 

disabling a transformer 299 

disabling conditions on links 301 

dumping the pipeline to serveryyyymmdd.log 311 

enabling a single flow step 298 

enabling a transformer 299 

modifying the pipeline 302 

overview 276, 288 

posting messages to serveryyyymmdd.log 310 

resetting debug mode 290 

stepping into a child flow 294 

stepping into a transformer 294 


Index

stepping through a flow 288, 292 

tracing a flow 288, 290 

tracing into a child flow 292 

using server debug facility 308, 309 

debugLog service 310 

decimal content constraint 456 

declaring 

input and output parameters 129 

input for a service 130 

output for a service 131 

default value, assigning to a pipeline variable 217 

defining packages 76 

deleting 


event subscriptions 370 


links between variables 214 

packages 81 

dependencies, package 

identifying 85 

removing 87 

dependents 

checking when renaming IS elements 47 

confirming before deleting elements 48 

finding service and document (IData object) 63 

safeguards for updating 48 

details perspective 36 

Developer window, toolbar 28 

Developer. See webMethods Developer 

dimensionality, definition of 228 

directories 

Java services 327 

Disable Step command 298, 299 

disabling 

a condition placed on a link 301 

a flow step 298 

a transformer 299 

dispatch services 

for COM 337 

for DCOM 337 

document (IData object) validation 


errors 468 

exceptions 482 

performing 269 

document data type 420 

document list data type 

converting from String list 210 


document reference data type 

creating 254 


document reference list data type 

creating 254 


Document Type Definitions. See DTDs 

document types. See IS document types 

documentation 

accessing for packages 80 

additional 18 

conventions used 17 

creating for packages 80 

feedback 18 

using effectively 17 

documents (IData objects) 

applying content constraints 454 

assigning to a document or document list 244, 254 

assigning to a specification 244 


creating 244 

errors when creating from DTD or XML Schema 486 

finding dependents 47 

linking 208 

open and closed 262 


printing 253 

using as service parameters 244, 253 

viewing in browser 253 

double content constraint 456 

DROP modifier 200, 220 

dropping values from the pipeline 220 


Index

DTDs 

creating documents (IData objects) from 244 

creating IS document types from 246 

creating IS schemas from 239 

IS schema generation warnings 486 

duration content constraint 457 

E 

early binding, for a Visual Basic service 339, 341 

edit perspective 36 

editing 

elements. See editor 

event subscriptions 369 


properties 32 

Service property 165 

simple types in IS schema 242 

editor 

described 30 

help about 41 

hiding and showing 35 

inserting flow steps into 161 

resizing 35 

supported data types 129 

tabs 30 

viewing and editing elements in 30 

element declaration 236 

element lock 

copying, moving, and deleting 100 

removing. See unlocking elements 

system lock 94 

user lock 94 

element reference 236 

elements (IS) 

See also editor 47 

assigning ACLs 113 

caching to improve Developer performance 70 

copying 51 

creating 45 

cutting 51 


deleting 57 

displayed in editor 30 


Index 

displayed in Navigation panel 25 

displayed in Recent Elements tab 29 

displayed in Servicenet tab 28 

double-clicking to open 49 

editing 47 

exporting 82 


finding in Navigation panel 59 

finding unresolved references 65 

fully-qualified names 45 

guidelines 

copying 51 

creating 45 

deleting 57 

general actions 48 

moving 51 

opening and closing 49 

renaming 55 

help for properties 41 

locating in Navigation panel 31 

locking 47 

moving 51 

naming guidelines 46 

overwriting when creating publishable document types 249 

pasting 51 

performing actions 48 

performing actions on 34 

permissions 110 

references 65 

renaming 55 

saving 57 

single-clicking does not open 49 

unlocking 47 

viewing as HTML 47 

empty 

content 237 

strings in filters 437 

values, branching on 172 

Enable service audtiting options, described 149 

Enable Step command 298, 299

enabling 

flow steps 298 

service auditing 149 


end-to-end linking 223 

entering input for a service 278 

ENTITIES content constraint 457 

ENTITY content constraint 457 

enumeration constraining facet 464 

envelope field 

in publishable document types 251 

usage restrictions 251 

error auditing, described 153 

error handling, in flow services 185 

errors 

data validation 468 

document (IData object) generation 486 

flow service generation 486 

IS schema generation 486 


Evaluate labels property 178 

event filters 

creating 366 

creating for services 368 

event handlers 

creating 370 

creating sample 371 


for alarm events 373 

for audit events 374 

for exception events 376 

for GD End events 380 

for GD Start events 379 

for port status events 381 

for replication events 382 

for session end events 383 

for session expire events 384 

for session start events 383 

for stat events 385 

for Tx End events 387 

for Tx Start events 387 

stages of creating 370 

Event Manager 

alarm events 

building handlers 373 


uses 373 

audit events 




event behavior 363 


Event Manager command 364 

exception events 362, 376 


filters 366 

GD End events 377 


uses 377 

GD Start events 377 


uses 377 

guaranteed delivery events 362 

pattern strings 366 

port status events 362, 380 


uses 380 

replication events 362, 381 


uses 381 

run-time behavior 363 

session end events 382 


session events 362, 382 

uses 382 

session expire events 382 


session start events 382 


stat events 363, 384 


uses 384 

subscriptions 

creating 364 


Index

creating filters for 366 

deleting 370 

editing 369 

managing 364 

suspending 369 

viewing 369 

transaction events 363, 386 

Tx End events 386 


uses 386 

Tx Start events 386 


uses 386 

viewing subscriptions 369 

events 

See also event handlers, Event Manager 

creating filters 366 

creating filters for services 368 

deleting subscriptions to 370 

editing subscriptions to 369 

guaranteed delivery 377 

subscribing to 364 

suspending subscriptions to 369 

types of 362 

viewing subscriptions to 369 

Excel clients, creating 355 

exception events 



exceptions 

data validation 273, 482 

during a test 284 

executing services from Developer 277 

execution locale 141 

Exit on property 185 

EXIT step 

creating 191 



expanding transformers 230 

explicit linking, definition of 202 

explicit universal names 146 

exporting elements and packages 82 

expressions 



branching on 171 

operator precedence 441 

operators for 434 

syntax for 431 

using for pipeline linking 214 

extending the Java class 322 

extends (Java keyword) 322 


F 

facets, See constraining facets 

failIfInvalid property 482 

failure 

of a flow step 185 

of a REPEAT step 180 

fields 

content type constraint symbol 265 

dagger symbol 265 

green squares 265 

optional symbol 265 

filter collation locale 437 

filtering events 366 

filters 



allowed quantifiers 446 

arrays 446 

back references 446 

booleans in 445 

braces {} in 446 

checking for variable existence 445 

collation locale, specifying 437 

comparing strings and numeric values 445 

comparison operators, missing 445 

constrained Objects in 445 

effect of locale 437 

extended metacharacters 446 

lexical relational operators 437 

lists 446 

logical operators 439 

$null 446 

Index

operators for 434 

server performance 435 


syntax 431 

syntax restrictions 444 

variables with special characters 443 

finding 

elements in Navigation panel 59 

invoked services 63 

service and document (IData object) dependents 63 

unresolved pipeline references 66 

unresolved references 65 

float content constraint 457 

flow services 

See also services, debugging flow services 

breakpoints 295, 296 


creating 127 

debugging 288 


disabling a single step 298 

disabling a transformer 299 

disabling conditions placed links 301 

editing 122 

enabling a single step 298 

enabling a transformer 299 

errors creating from DTD or XML Schema 486 

inserting steps in a service 161 

maximum retry period 143 

printing 157 

response to failure 185 

retrying 143, 144 



stepping in/out of transformers 294 

stepping through 292 

tracing 290 


flow steps 

BRANCH 124, 168 

changing the level of 162 

changing the position of 162 


disabling 298 

enabling 298 

EXIT 124, 190 

failure of 185 

grouping 185 

hierarchical order of 162 

inserting into a flow service 160 

INVOKE 123, 165 

LOOP 124, 186 

MAP 124, 192 

moving in a flow service 162 

parent/child relationships 162 

properties 163 

re-enabling 298 

REPEAT 124, 179 

SEQUENCE 124, 185 

setting breakpoints on 296 

folders, creating 127 

frag mode (jcode) 331 


G 

GD End events 



pub.remote.gd:end 377 

uses of 377 


GD Start events 



pub.remote.gd:start 377 

uses of 377 


gDay content constraint 458 

Generate Code command 349, 351, 353 

global declarations, in XML Schemas and DTDS 236 

gMonth content constraint 458 

gMonthDay content constraint 458 

Go To Breakpoint command 298 

Go To command (for services) 63 

gray links, in the Pipeline tab 202 

green square, next to variable icon 265 

grouping flow steps 185 

Index

guaranteed delivery events 

See also GD End events, GD Start events 

compared to transaction events 378 


generating guaranteed delivery (GD) events 378 

generating transaction (Tx) events 378 

overview 378 


guidelines 

for assigning startup, shutdown, and replication services 89 

for elements 

creating 45 

deleting 57 

moving and copying 51 

opening and closing 49 

renaming 55 

working with 48 

for linking array variables 213 

for linking document (IData object) variables 208 

for linking variables 204 

for linking variables of different data types 209 

for naming packages 76 

gYear content constraint 459 

gYearMonth content constraint 459 

H 

hailmary mode (jcode) 332 

hard-coding input variables 216 

help, obtaining 41 

hexBinary content constraint 459 

hiding and showing panels 35 

HTML, viewing elements in 47 

I 

ID content constraint 459 

IData objects 

creating 317 


getting data from 317 

positioning cursors 317 

putting data in 317 

using in a Java service 328 

IDE 

assigning a super class with 322 

creating source code in 320 

defining private methods with 322 

implementing interfaces with 322 

importing Java packages 322 

in Developer 318, 320 

using other IDEs 327 

using the Java service editor 320 

using the Shared tab 322 

identifying 

package dependencies 85 




IDREF content constraint 460 

IDREFS content constraint 460 

implementing interface in Java services 322 

implements (Java keyword) 322 

implicit linking 

described 202 

for MAP steps 223 

implicit universal names 146 

import (Java keyword) 322, 328 

import mechanism, in XML Schemas 241 

importing Java packages 322, 328 

include mechamism, in XML Schemas 241 

index, array variables 212 

Indexing tab. See linking array variables 

Input array property 187 

input variables 

declaring for a service 129, 130 

declaring in a document (IData object) 244 

entering test values for 278 

hard-coding 216 

linking considerations 204 

linking in the pipeline 202 

loading values from a file 280 

saving values to a file 280 

input/output parameters 

declaring for a service 129 

generating Java code from 325 

Input/Output tab 131 


Index

input/output validation 


performing via Input/Output tab 267 

performing via INVOKE step 268 

inserting 

INVOKE step 167 

steps into flow services 161 


installing Java services 327 

int content constraint 460 

integer content constraint 460 

Integrated Development Environment. See IDE 

Integration Server Administrator, unlocking elements 101 

Integration Server. See webMethods Integration Server 

interfaces 

implementing in Java service 322 

INVOKE step 

Comments property 402 

creating 167 


finding 63 

invoking built-in services 166 

invoking services on another server 166 

Label property 403 

peforming validation via step properties 268 

Pipeline tab 197 

Scope property 402 

Service property 165, 403 

Timeout property 402 


Validate input property 403 

Validate output property 403 

invoking 

built-in services 166 

remote services 166 

services 167 

services from a browser 357, 359 

services on another server 166 

Visual Basic services 339 

IS document types 

See also documents (IData objects) 

creating empty document types 245 

creating from Broker document type 248 

creating from DTD 246 

creating from XML document 246 

creating from XML Schema 246 

described 244 

editing 252 

IS elements. See elements (IS) 

IS schemas 

appearance 234 

constraints 234 


creating 239 


editing simple types 242 

errors from generating 486 

generating multiple 241 

import element 241 

include element 241 


using to validate an XML document 271 

warnings from generating 486 

ISRuntimeExceptions 

description of 143 

throwing in services 390 


J 

Java classes for object and object list variables 421 

Java clients, creating 346, 349 

Java keywords 

extends 322 

implements 322 

import 322, 328 

Java service editor 320 

Java services 

adding private methods to 322 

compiler location 324 

compiling with Developer 324 

compiling with jcode 330 


creating with an IDE 327, 329 

creating with Developer 319 

extending the class of 322 

implementing interface in 322 

importing packages into 322, 328 

Index

installing manually 327 

jcode requirements 329 

location of class files 327 

location of source files 328 

publishing to the server 327 

required code 328 

setting run-time options 326 

stages of development 319 

structure of 318 

using with webMethods components 318 

validating from 271 

jcode utility 

composite mode 331 

frag mode 331 

hailmary mode 332 

make mode 330 

purpose of 327 

source code samples 448 

source code tags 329 

update mode 332 

K 

keyboard shortcuts 34 

L 

L_EQUALS 438 

L_GREATER_OR_EQUAL 438 

L_GREATER_THAN 438 

L_LESS_OR_EQUAL 438 

L_LESS_THAN 438 

L_NOT_EQUALS 438 

Label property 

definition 403 

for evaluating expressions 171 

for general use 164 

for specifying the default BRANCH step 174 

for targeting BRANCH steps 170 

language content constraint 460 

late binding, for a Visual Basic service 339 

length constraining facet 465 

lexical relational operators 

conditional expressions 437 


empty string 437 

locale 437 

non-string variables 437 

libs directory 332, 336, 339 

link indices 212 

linking 

array variables 211 

default rules 424 

guidelines for 213 

to array variables 424 

to scalar variables 424 

to transformers 228 

between document formats 223 

conditional links 214 

considerations 204 

copying by reference 206 

copying by value 206 

default behavior for arrays 213 

deleting links between variables 214 

different data types 209 

disabling conditions on links 301 

document (IData object) variables 208 

in a single view 223 

input variables 202 

output variables 203 

pipeline variables to service variables 201 

scalar variables to array variables 424 

the pipeline 205 


variables conditionally 214 

variables explicitly 202 

variables implicitly 202 

links 

blue colored 212 

deleting 214 

disabling conditions 301 

executing at run time 206 

gray colored 202 

in Pipeline tab 201 

list variables in filters 446 

Load Pipeline Locally command 306 


Index

loading 

input values from a file 280 

pipeline values from a file 

into Results panel 306 

overview 306 

with restorePipelineFromFile service 307 

locating a breakpoint 298 

locking elements 

corresponding server files 103 

description 94 

Java and C/C++ 97 

single element 96 

system locking 98 

template service 98 

unlocking. See unlocking elements 

VCS check in/check out 94 

viewing lock status 95, 99 

log files, audit log 149 

logging on to webMethods Integration Server 22, 37 

logical operators, definition of 434 

long content constraint 460 

LOOP step 

creating 189 

creating nested loops 187 


setting Input array 187 

setting Output array 188 


M 

make file 

creating 332 

using to compile C/C++ services 336 

make mode (jcode) 330 

MAP modifier 


executing at run time 206 

linking different data types 209 

linking from service output 203 

linking to service input 202 

MAP step 

debugging 294 


disabling transformers 299 

enabling transformers 299 

inserting transformers 224 




using to initialize variables in a flow 193, 218 

mapping. See linking 

Max attempts property 145 

maxExclusive constraining facet 465 

maximum retry period, definition of 143 

maximum retry period, description of 143 

maxInclusive constraining facet 465 

maxLength constraining facet 465 

maxOccurs threshold value, for validation 274 

memory 

reducing usage 70 

running out of during validation 274 

menu bar, using to perform actions 34 

metacharacters, in filters 446 

methods, adding to a Java service 322 

minExclusive constraining facet 465 

minInclusive constraining facet 465 

minLength constraining facet 465 

mixed content 237 

modifying the pipeline 200 

moving 


steps in a flow service 162 

steps within a flow 162 


N 

Name content constraint 461 

name transformations, definition of 196 

namespace information (for services) 

creating source file from 331, 332 

location of 327 

updating with jcode 331 

namespaces 

usage in universal names 145 

XML namespace property 255 

naming services 45 

Navigation panel 

Index

described 24 

help about 41 


icons 25, 94 

refreshing contents of 27 

resizing 35 

toolbar 28 

NCName content constraint 461 

negativeInteger content constraint 461 

NMTOKEN content constraint 461 

NMTOKENS content constraint 461 

nonNegativeInteger content constraint 461 

nonPositiveInteger content constraint 462 

not operator 439 

notification, of server shutdown 39 

ns directory 327 

$null 

in filters 446 

in labels for BRANCH steps 173 

null, branching on 172 

O 

Object data type 


in filters 445 

Object list data type, definition of 421 

object list variables, Java classes 421 

object variables, Java classes 421 

online help, obtaining 41 

open and closed documents 262 

open documents, described 262 

opening a session on webMethods Integration Server 37 

operations, performing on IS elements 34 

operators 

conditional expressions and filters 434 

lexical relational operators 437 

logical 439 

precedence in expressions 441 

relational 434 


optional variables for validation 262 

or operator 439 

out of sync publishable document types 253 

Output array property 188 

output templates 

assigning to a service 134 


output variables 

declaring 131 

declaring for a service 129 


linking considerations 204 

linking in the pipeline 203 

Overwrite Pipeline Value option 217 


P 

packages 

adding 76 

assigning version numbers 83 

copying 78 

creating 76 

creating circular dependencies 87 

cutting 78 


deleting 81 

dependencies, using with startup services 88 

documenting 80 

exporting 82 

identifying dependencies 85 

importing into Java services 322, 328 

moving 78 

naming guidelines 76 

pasting 78 

reloading 81 

reloading vs refreshing 81 

removing dependencies 87 

required by Java services 328 

viewing details 77 

viewing patch history 83 

Index

panels 

editor 30 

Navigation 24 

Properties 31 

Recent Elements 29 

Results 33 

Servicenet 28 

switching perspectives 36 

parameters 


benefits of declaring 129 

declaring 129, 133 

declaring for a service 130, 131 

parent/child relationships in a flow 162 

passwords 

changing 39 

requirements 39 

patch history 

removal by Integration Server 84 

viewing for a package 83 

pattern constraining facet 465 

pattern matching, in event subscriptions 366 

Perform Variable Substitution option 218 

Performance 152 

performance impact, service auditing 152 

permission 

See also ACLs 

assigning to elements 110 

Permissions property 114 

perspectives of views 36 

pipeline 

adding variables to 221 


adjusting 200 

assigning values to 216 

changing values 302 

checking for variables 434 

conditional linking 214 

copying values 219 


DROP modifier 220 

dropping values 302 

dropping variables from 220 

inspecting modifiers 66 

linking 205 




input variables 202 


scalar variables, default rules 424 


variables of different data types 209 

MAP step 192 

modifying 302 

Overwrite Pipeline Value option 217 

Perform Variable Substitution option 218 

Pipeline In 197 

Pipeline Out 198 

restoring from a file 306 

saving 303 

saving from Results panel 304 

saving with savePipelineToFile service 305 

Service In 197 

Service Out 198 

SET VALUE modifier 216 

stages of 197 

validating 270 

validating via built-in services 270 

validating via Java service 271 

viewing after run-time exception 286 

viewing with Developer 281 

Pipeline Editor. See Pipeline tab 

Pipeline In 197, 199 

pipeline modifiers 


DROP 200 

MAP 200 

SET VALUE 200 

Pipeline Out 198, 199 

pipeline references 


finding 66 


blue links (conditional link) 212 



Index


default behavior for arrays 213 

default linking rules 424 

deleting links between variables 214 

editing a MAP step 199 

editing INVOKE step 197 

gray links (implicit link) 202 

inserting transformers 224 

linking 




document (IData object) variables 208 

scalar variables, default rules 424 


variables 201 

overview 196 

printing 200 

transformer movement 227 


pipeline validation 


errors 468 


performing via built-in services 270 

performing via Java service 271 

port status events 



uses of 380 

positiveInteger content constraint 462 

precision constraining facet 466 

prefetch 140 

preserve white space 466 

printing 

documents (IData objects) 253 


Pipeline tab contents 200 

private methods, defining in Java service 322 

program code conventions in this document 17 

programming languages 

creating services with 316 

supported 316 

properties 

Audit level 156 

auditLog server 156 

Comments 164, 402 


editing 32 

Evaluate labels 178 

Exit on 185 

for transformers 225 

Input array 187 

Label 164, 403 

Label (for BRANCH steps) 170, 174 

Output array 188 

Permissions 114 

Repeat on 180, 181, 408 

Scope 177, 402 

Service 165, 167, 225, 403 

setting for variables 255 

Switch 170, 178 

Timeout 167, 177, 181, 182, 189, 402 

Validate input 167, 225, 403 

Validate output 168, 225, 403 

XML Namespace 255 

Properties panel 

auditing a service 148 

described 31 

flow step properties 163 

help about 41 


patch history for packages 84 

resizing 35 

run-time parameters 137 

pub.flow:getRetryCount service 145 

pub.flow:throwExceptionForRetry service 144 

invoking 393 

pub.publish:envelope document type 251 

pub.remote.gd:end service 377 

pub.remote.gd:start service 377 

pub.remote:invoke service 166 

pub.schema:validate service 269 

pub.schema:validatePipeline service 270 


Index

publishable document types 

adapter notifications 252 

creating from Broker document type 248 

defined 249 

editing 253 

envelope field 251 

overwriting elements 249 

synchronizing 253 

publishing services to the server 327 

R 

Recent Elements tab 

described 28, 29 

help about 41 


resizing 35 

Record data type. See document data type 

Record list data type. See document list data type 

Record Reference data type. See document reference data type 

Record Reference List data type. See document reference list 

data type 

records. See document (IData object), IS document types 

redefine mechanism, in XML Schemas 241 

re-enabling 

flow steps 298 


referenced elements, importing during synchronization 249 

references 

finding 65 

inspecting pipeline 66 

refresh 

difference from restoring a session 39 

Navigation panel contents 27 

Recent Elements tab contents 29 

regular expressions 

creating event filters with 368 


operators 413 

using as a BRANCH label 170 

using in a mask 412 

reinvoking services 153 

relational operators 


lexical 437 

standard 435 

types of 434 

reloading packages 81 

remote servers, invoking services on 166 

remote services, invoking 166 

removing 

breakpoints 298 

breakpoints from transformers 297 

package dependencies 87 

packages 81 




variables from the pipeline 220 

renaming 



Repeat on property 180, 181, 408 

REPEAT step 

creating (on failure) 181 

creating (on success) 183 


failure 180 

specifying the repeat condition 180, 408 


using to retry a failed step 181 

using to retry a successful step 183 

replace white space 466 

replication events 



uses of 381 

replication services 

assigning 90 


guidelines for assigning 89 

removing 91 

when to use 89 

requirements for passwords 39 

requiring variable existence for validation 262 


Index

Reset command 290 

resizing 

panels 35 

window areas 35 

Restore Pipeline from Server command 306 

Restore Pipeline Locally command 306 

restorePipelineFromFile service 303, 306 

restoring 

pipeline values from a file 

into Results panel 306 

overview 306 

with restorePipelineFromFile service 307 

sessions 38 

Results panel 

copying elements from 283 

described 33 

general information 282 

help about 41 


resizing 35 

saving results from 303 

retried audit log status 143 

Retry interval property 145 

Retry on ISRuntimeException category 145 

retry period, maximum 143 

retry, for service 143 

retrying a flow step 179 

Run command 277 

Run in Browser command 286 

running out of memory, during validation 274 

running services from Developer 277 

run-time exceptions 284 

run-time settings 326 

S 

Save Pipeline Locally command 304 

Save Pipeline to Server command 304 

savePipelineToFile service 305, 306 

saving 

changes to elements 57 

elements (IS) 57 

input values to a file 280 

test results from Results panel 304 

test results using savePipelineToFile service 305 

test results, overview 303 

scalar variables 

default behavior for linking 424 


linking to or from array variables 424 

scale constraining facet 464 

schema browser, definition of 235 

schema details area, definition of 238 

schema editor 234 

schema processor, definition of 239 

schema services 

for document (IData object) validation 269 



Scope property, definition 402 

Send XML File command 287 

sequence content model 237 

SEQUENCE step 

as target for a BRANCH 175 


setting exit condition 185 


server files, viewing for locked elements 103 

server. See webMethods Integration Server 

serveryyyymmdd.log file 309 

contents of 309 

dumping pipeline to 311 

overview 308 

posting messages to 310 

service auditing 


described 148 

enabling 149 

error auditing 153 

failed and successful services 154 

including pipeline 151 

overwriting individual service settings 156 

performance impact 150, 152 

specifying which states to log 149 

use cases 153 

Service In 197 

Service Out 198 


Index

Service property 



editing 165 

for transformers 225 

renaming transformers with 231 

service retry 

adapter services 390 

audit log 143 

basic componenents 391 


example 394 

overview 390 

requirements 144, 390 

restrictions 144 

throwing exceptions for 390 

services 

assigning universal names 145 

audit data 

enabling 149 


auditing 


enabling 149 

for recovery 155 

long-running services 155 

options 155 


configuring retry 143 

creating event filters for 368 

creating flow 127 

creating with Visual Basic 336, 339 

execution locale 141 


finding invoked 63 

flow control 123 

input signature for trigger services 131 

invoking built-in 166 

invoking on another server 166 

invoking on remote servers 166 

locale policy 141 

naming 45 

provided by webMethods Integration Server 166 


Index 

reinvoking 153 

retry exceptions 390 

retryiing 144 

retrying adapter services 390 


state information 137 

testing and debugging 276 

throwing retry exceptions 390 


validating input/output via Input/Output tab 267 

validating input/output via INVOKE step 268 

session 

closing on webMethods Integration Server 37 

opening on webMethods Integration Server 37 

restoring 38 

session end events 



session events 

See also session end events, session expire events, session 

start events 


uses of 382 

session expire events 



session start events 



Set Breakpoint command 296 

SET VALUE modifier 200, 216 

copying 219 

using in MAP step 218 

setting 

breakpoints on flow steps 296 


variable values 216 

Settings tab. See Properties panel 

Shared tab 322 

short content constraint 462 

shortcuts, for toolbars 28 

showing and hiding panels 35

shutdown services 

assigning 90 



removing 91 


signature 

for trigger services 131 

of a service 316 

simple types 237 

editing in IS schema 242 

single view linking 223 

source code 

compiling Visual Basic 339 

compiling with C/C++ make file 336 

compiling with jcode 330, 332 

creating automatically for a Java service 325 

creating from namespace information 331 

creating in your own Java IDE 328 

creating Java 326 

location of 328, 339 

tagging for jcode 329 

writing in C/C++ 335 

writing in Developer 320 

source control system, integration with 94 

Source field on Shared tab 322 

Source tab. See Java service editor 

special characters 

in variable names 443 

typing in expressions 443 

specifications 



creating 256 



squares, green 265 

stack overflow, during validation 274 

standard relational operators 


using in filters 435 

using in triggers 435 

starting Developer 21 

startup services 

assigning 90 


effect on package dependencies 88, 91 


removing 91 


stat events 



uses of 384 

state information for a service 137 

status events. See port status events 

Step command 288, 292, 293 

Step Into command 288, 292, 294 

Step Out command 292, 294 

stepping through a flow 288, 292 

string content constraint 462 

String data type, definition of 420 

String list data type 

converting to document list 210 


String table data type 420 

strings 


transformation services 224 

structural constraints 


for validation 261 


IS schemas 234 

structural transformations 


examples 210 

linking to resolve 209 

subordinate flow steps. See child flows 

subscribing to events, overview 364 

super class, defining in IDE 322 

suspending event subscriptions 369 

Switch property 170, 178 

switch value, branching on 169 


Index

symbol 

for content type constraints 265 

for optional variables 265 

syntax for conditional expressions and filters 431 

system locking 

defined 94 

elements 98 

T 

tables, support of 423 

tabs 

Input/Output tab 131 


Schema tab. See schema editor 234 

selecting 30 

Settings tab for services. See also Properties panel 326 

Shared tab 322 

tagging source code for jcode 329 

templates 



test perspective 36 

test results 

changing pipeline values 302 

copying 283 

loading 303 

saving 303 

viewing 281 

testing services 

entering test input 278 

from a browser 286 

from Developer 277 

inspecting the pipeline 281 

loading input values from a file 280 

loading the pipeline 303 

overview 276 

run-time exceptions 284 

saving input to a file 280 

saving the pipeline 303 

setting breakpoints 295 

testing in debug mode 288 

viewing results 281 

viewing the call stack 285 

viewing the pipeline 286 

XML document as input 287 

threshold value, for maxOccurs 274 

throw exception for retry 391 

time content constraint 463 

time conversion services 224 

timeDuration content constraint 457 

Timeout property 167 


for BRANCH step 177 

for LOOPstep 189 

for REPEAT step 181, 182 

token content constraint 463 

toolbar, Developer window 28 

toolbar, using to perform actions 34 

totalDigits constraining facet 466 

Trace command 288, 290, 291 

Trace Into command 288, 290, 292 

and breakpoints 296 

effect on breakpoints 296 

Trace to Here command 288, 290, 291 

tracePipeline service 311 

tracing 

a flow 288, 290 

into a child flow 292 

transaction events 

See also Tx End events, Tx Start events 

compared to guaranteed delivery events 378 


uses of 386 


Transformer not found message 231 

transformers 

adding 224 


clearing breakpoints 297 

collapsing 230 

considerations 224 

copying 230 

debugging 294 


dimensionality mismatch 228 

disabling 299 


Index

enabling 299 

expanding 230 

inserting 224 

linking 226 

linking array variables 228 

movement in Pipeline tab 227 


properties 225 

re-enabling 299 

renaming 231 

Service property 225 

services provided by webMethods 224 

setting breakpoints 297 


Validate input property 225 

Validate output property 225 

validating input and output 229 

zooming in on 230 

transient error, definition of 143, 390 

trigger services, input signature requirements 131 

triggers 

creating filters for 430 

description of 25 

disabled when copied 52 

filter syntax restrictions 444 

filters and relational operators 437 

lexical operators 434 

testing 276 

used with adapter notifications 252 

using standard relational operators 435 

troubleshooting information 18 

try sequence, in service retry 391 

Tx End events 



uses of 386 


Tx Start events 



uses of 386 


type definitions 

anonymous 237 

complex types 237 

simple types 237 

typographical conventions in this document 17 


U 

Unicode, and Java source code 331 

universal names 

assigning to services 145 

implicit vs explicit 146 

local portion of name 145 

namespace portion of name 145 

removing from a service 147 

unlocking elements 

more than one 99 

system locked 103 

using Integration Server Administrator 101 

using webMethods Developer 100 

unresolved references, finding 65 

unsignedByte content constraint 463 

unsignedInt content constraint 463 

unsignedLong content constraint 464 

unSignedShort content constraint 464 

update mode (jcode) 332 

URL, invoking services from 357, 359 

user account on webMethods Integration Server 20 

V 

Validate input property 167, 225 


Validate output property 168, 225 


validatePipeline service 270 

validating 

See also validation 

documents (IData objects) 269 

from Java services 271 

input/output for transformers 229 

input/output via Input/Output tab 267 

input/output via INVOKE step 268 

pipeline via built-in services 270 

pipeline, overview 270 

Index

service input/output 266, 267, 268 

XML documents 271 

validation 

See also validating 

allowing undeclared variables 262 



blueprints for 260 

constraining facets 464 

constraints, definition of 261 



errors 273, 468 

exceptions 273, 482 

input/output 266 

overview 260 

requiring variable existence 262 

running out of memory 274 

service input and output 266 

stack overflow 274 

types of 260 

XML validation 271 

validation errors and error codes 468 

validation services 

pub.schema:validate 269, 271 

pub.schema:validatePipeline 270 

value transformations, definition of 196 

variables 

adding to the pipeline 221 

addressing in the pipeline 441 


applying content constraints 454 

applying content types 262 

checking for existence 434 

content type constraint symbol 265 



copying values in pipeline 219 

declaring for a service 129, 130, 131 


deleting links 214 

initializing values 218 

linked by blue line 212 

linking 202 

linking conditionally 214 

optional existence for validation 262 

optional symbol 265 

requiring existence for validation 262 

setting properties 255 

substitutions 218 

using as Set Value 218 

viewing applied constraints 265 

XML Namespace property 255 

VCS Integration feature, described 94 

version control system (VCS), integration with 94 

version numbers, assigning to packages 83 

View as HTML command 157, 200, 253 

view perspectives 36 

viewing 

assigned value of a variable 217 

breakpoints list 298 

elements in HTML 47 

status of a locked element 95, 99 

test results 281 

variable constraints 265 

Visual Basic clients, creating 352 

Visual Basic services 


early binding 339, 341 

invoking early binding service 341 

invoking late binding service 339 

late binding 339 

win32.COM:invoke 339, 341 

win32.COM:invokeLate 339 


W 

warnings 

document (IData object) generation 486 

flow service generation 486 

IS schema generation 486 

watt.server.auditLog property, described 156 

watt.server.invoke.maxRetryPeriod 144 

watt.server.stats.pollTime property 380 

webMethods API, for Java 328 

Index

webMethods Developer 

main window 23 

online help 41 

starting 21 

toolbar 28 


access requirements for 20 

closing a session 37 

connecting to 22, 37 

disconnecting from 37 

logging on to 22 

notification of shutdown 39 

opening a session 37 

performing ACL checking 111 

supported data types 420 

webMethods Monitor 148, 153 

webMethods Type Library 348, 352, 355 

When to include input pipeline options, described 151 

When to log options, described 149 

whiteSpace constraining facet 466 

win32.COM.dispatch:createObject 337 

win32.COM:invoke 339, 341 

win32.COM:invokeLate 339 

windows 

layout 23 

zooming 35 

WmPublic package, definition of 166 

WmVBDemo.vbp 339 

X 

XML documents 




testing services with 287 

XML Namespace property, described 255 

XML Schema definitions 




import mechanism 241 

include mechanism 241 

IS schema generation warnings 486 

redefine mechanism 241 

referenced by other XML Schemas 241 

XML validation 


creating IS schemas 239 


errors 468 


IS schemas, overview 234 

performing 271 



Z 

zooming 

in a window 35 

in on transformers 230 

Index

Index

webMethods Developer User's Guide - Software AG Documentation

Create successful ePaper yourself

Delete template?

Save as template?