8-2-SP2 Developer Users Guide PDF

Title Page
Developing Integration Solutions
webMethods Developer User’s Guide

Version 8.2
October 2011
Copyright
& Docu-
ment ID
This document applies to webMethods Developer Version 8.0 and webMethods Integration Server Version 8.2 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 1998–2011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or
their licensors.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
http://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG’s licensing conditions and terms. These terms are part of the product
documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products." This document is part of the product documentation, located at
http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
Document ID: DEV-UG-82SP2-20130301

Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Deprecation of webMethods Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Getting Started with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
The Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Navigation Panel Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Refreshing the Contents of the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . 29
The UDDI Registry Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
UDDI Registry Tab Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
The Recent Elements Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
The Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
The Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Moving Between Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Performing Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Resizing Areas in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Hiding and Showing Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Dragging Movable Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Switching Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Restoring a Session on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Notification of Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2. Managing Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
About Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Package Names and Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Guidelines for Naming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Editing Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 3

Table of Contents
Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Moving and Copying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Copying Elements Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Moving and Copying Adapter Notifications and Related Elements . . . . . . . . . . . . . . . . 55
Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Finding Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Finding Fields in Editor Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Locating Invoked Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Finding Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Finding References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Clearing the Developer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3. Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Guidelines for Naming Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Viewing Details for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Optimizing Lock Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Copying a Package to Another Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Documenting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Exporting a Package or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Assigning a Version Number to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Viewing the Patch History for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Identifying Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Removing Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
What Is a Shutdown Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Guidelines for Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . 91
Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . 92
Removing Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . 93
4 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

Table of Contents
Publishing and Retracting Information about Integration Server and Trading Networks Assets
93
Publishing Metadata about Integration Server and Trading Networks Assets . . . . . . . 94
Retracting Published Metadata about Integration Server and Trading Networks Assets 95
Usage Notes for Publishing/Retracting IS Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Checking the Status of Publication and Retraction Requests . . . . . . . . . . . . . . . . . . . 98
Status Information for Publication and Retraction Requests . . . . . . . . . . . . . . . . . 98
4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
How Do I Know Who Has an Element Locked? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
When Do I Lock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
When Do I Unlock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Unlocking Elements Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Unlocking an Element Using the Integration Server Administrator . . . . . . . . . . . . . . . . 110
Unlocking a System Locked Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Viewing an Element’s Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . . 112
Automatically Unlocking Elements After Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Lock/Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5. Assigning and Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
What Is an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
What Happens When a Client Runs a Service with ACLs? . . . . . . . . . . . . . . . . . . . . . 119
Am I Required to Use ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
How Do I Create an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
The Permissions Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Default ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Table of Contents
How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

ACLs and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
ACLs and Testing/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
What Is a Flow Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
What Is the Pipeline? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
What Are Input and Output Parameters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Package and Folder Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Using the Default Logic Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Specifying Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Specifying Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Completing the Input/Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Maintaining the State of a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Configuring a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Types of Services to Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Services Suited for Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Services that You Should Not Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Controlling a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Specifying the Duration of a Cached Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Using the Prefetch Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Specifying the Execution Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Setting Up URL Aliases for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Creating a Path Alias for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using the Pipeline Debug Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the Pipeline Debug Property to Save the Service Pipeline . . . . . . . . . . . . . 153
Using the Pipeline Debug Property to Restore the Service Pipeline . . . . . . . . . . . 154
Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Assigning Universal Names to Services and Document Types . . . . . . . . . . . . . . . . . . . . . . 157
Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Enabling Auditing for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Specifying When Audit Data Is Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Table of Contents
Including the Pipeline in the Service Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

When Is a Copy of the Input Pipeline Saved in the Service Log? . . . . . . . . . . . . . 163
Service Auditing Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Error Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Auditing for Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Auditing Long-Running Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Setting Auditing Options for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Audit Level Settings in Earlier Versions of Developer . . . . . . . . . . . . . . . . . . . . . . . . . 168
Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7. Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Changing the Position of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Changing the Level of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Setting the Properties of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Specifying the Service Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Invoking a Built-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Invoking a Service on Another webMethods Integration Server . . . . . . . . . . . . . . . . . . 178
Building an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Specifying the Switch Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Specifying the Label Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Branching on an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Branching on Null and Empty Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Specifying a Default Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Using SEQUENCE as the Target of a BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Building a BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Specifying the REPEAT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Setting the REPEAT Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Using REPEAT to Retry a Failed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Using REPEAT to Retry a Successful Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Using SEQUENCE to Specify an Exit Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Specifying the Input Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Collecting Output from a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Building a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Table of Contents
8. Mapping Data in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Pipeline Tab for an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Pipeline Tab for a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Pipeline Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Printing the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Linking Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
What Happens When Integration Server Executes a Link Between Variables? . . 217
Linking to Document and Document List Variables . . . . . . . . . . . . . . . . . . . . . . . . 220
Linking Variables of Different Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Examples of Structural Transformations on the Pipeline Tab . . . . . . . . . . . . 221
Converting a String List to a Document List . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Guidelines for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . 224
Deleting Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Applying Conditions to Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Linking Multiple Source Variables to a Target Variable . . . . . . . . . . . . . . . . . 226
Assigning Values to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Assigning a Default Value to a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Initializing Variables in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Referencing Other Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Setting a Value for a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Copying Set Values Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Dropping Variables from the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Adding Variables with the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
What Are Transformers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Using Built-in Services as Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Inserting a Transformer into a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Linking Variables to a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Transformer Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Transformers and Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
What Is Dimensionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Validating Input and Output for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Copying Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Expanding Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Renaming Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Debugging Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . . . . . . . . 245

Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Table of Contents
What Does an IS Schema Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Schema Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Schema Details Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
About Schema Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Creating IS Schemas from XML Schemas that Reference Other Schemas . . . . . 253
Editing a Simple Type in an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Setting Constraining Facet Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . . 258
Points to Consider for All Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Points to Consider When Using a DTD As the Source . . . . . . . . . . . . . . . . . . . . . 258
Points to Consider When Using an XML Schema As the Source . . . . . . . . . . . . . 259
Expanding Complex Document Types Inline . . . . . . . . . . . . . . . . . . . . . . . . . 260
Generating Fields for Substitution Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Creating an IS Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . 265
The Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . 268
Assigning Universal Names to an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . 268
Editing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Printing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Using an IS Document Type to Specify Service Input or Output Parameters . . . . . . . 270
Using an IS Document Type to Build a Document Reference or Document Reference List
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Specifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
10. Performing Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
What Is Data Validated Against? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Considerations for Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Customizing a String Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Viewing the Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Specifying Input/Output Validation via the Input/Output Tab . . . . . . . . . . . . . . . . . . . . 285
Specifying Input/Output Validation via the INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . 286
Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . 288
Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Table of Contents
Running Out of Memory During Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11. Testing and Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Entering Input for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Saving Input Values to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Loading Input Values from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Viewing the Results of the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Copying Variables from the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Run-Time Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
The Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
The Pipeline Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Entering Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Combining the Step and Trace Commands in Debug Mode . . . . . . . . . . . . . . . . . . . . 307
Resetting Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Using the Trace Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Tracing into a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Using the Step Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Stepping Through a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Using the Step Tools with a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
What Happens When a Breakpoint Is Encountered? . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Setting Breakpoints on Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Viewing a List of Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Disabling Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Disabling Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Disabling a Condition Placed on a Link Between Variables . . . . . . . . . . . . . . . . . . . . . 318
Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Saving the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Saving the Contents of the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Automatically Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Manually Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Loading a Saved Pipeline into the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . 324
Automatically Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . 325
Manually Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . 325
Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Using the Server’s Debug Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Table of Contents
The Contents of the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Server Debug Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Writing Information to the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Writing an Arbitrary Message to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Dumping the Pipeline to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
12. Building Coded Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
The IData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Services Take IData Objects as Input and Return IData as Output . . . . . . . . . . . 332
Getting and Setting Elements in an IData Object . . . . . . . . . . . . . . . . . . . . . . . . . 333
Creating IData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Using the Developer IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
The Java Service Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
The Shared Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Creating a Java Service with Developer’s IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Generating Java Code from Service Input and Output Parameters . . . . . . . . . . . 339
Setting Run-Time Options for a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
The Namespace Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
The Source Code Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Writing the Source Code for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Using the webMethods API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
The Basic Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Commenting Code for the webMethods Integration Server . . . . . . . . . . . . . . . . . 344
Using the jcode Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Make Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Fragment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Composite Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Other jcode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Generating Files for a C/C++ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
The Java Code for a C Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Building the C/C++ Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . 352
Creating the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Invoking the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
13. Creating Client Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Table of Contents
Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
General Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Files for the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Files Containing the Code that Invokes the Service . . . . . . . . . . . . . . . . . . . . . . . 362
File Containing the Code that Interacts with webMethods Integration Server . . . . 362
Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Invoking Services with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Using the HTTP GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Using the HTTP POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Input to the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Controlling How Integration Server Handles Duplicate Tokens in Input . . . . . . . . 369
Output from the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Building a REST Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
14. Submitting and Receiving XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Example: Submitting XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Example: Receiving XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Example: Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . 374
Submitting and Receiving XML via $xmldata without Parsing . . . . . . . . . . . . . . . . . . . 375
Example: Submitting and Receiving XML via $xmldata without Parsing . . . . . . . . . . . 375
Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Table of Contents
Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Example: Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Submitting and Receiving XML via HTTP without Parsing . . . . . . . . . . . . . . . . . . . . . . 378
Example: Submitting and Receiving XML via HTTP without Parsing . . . . . . . . . . . . . . 378
Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
FTPing a File from a webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 380
Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Example: Sending XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
15. Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
What Are Event Handlers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
What Happens When an Event Occurs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Subscribing to an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Creating Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Creating Event Filters for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Viewing and Editing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Suspending Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Deleting an Event Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Sample Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Invoking Event Handlers Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . 398
Working with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Guaranteed Delivery Events and Transaction Events . . . . . . . . . . . . . . . . . . . . . . 400
Working with JMS Delivery Failure Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Working with JMS Retrieval Failure Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Working with Security Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
16. Building Services that Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Table of Contents
Adapter Services and Retry Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
How to Build a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . 410
Example—Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . 412
A. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Branching on Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Conditions that Will Cause a BRANCH Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Conditions that Will Cause an INVOKE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Conditions that Will Cause a LOOP Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Example of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Conditions that Will Cause the SEQUENCE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . 430
B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
C. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Java Classes for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
How webMethods Developer Supports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . 444
D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Comparing Java Objects to Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Table of Contents
Checking for Variable Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Standard Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Lexical Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Addressing Variables that Contain Special Characters . . . . . . . . . . . . . . . . . . . . . . . . 461
Typing Special Characters in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Sample Code—IData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
F. Validation Content Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
G. Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

Table of Contents

About This Guide
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.
Note: This guide describes features and functionality that may or may not be available
with your licensed version of webMethods Integration Server. For information about
the licensed components for your installation, see the Settings > License page in the
webMethods Integration Server Administrator.
Deprecation of webMethods Developer

webMethods Developer is deprecated and does not support all the features of
webMethods Integration Server 8.2. Software AG recommends the use of webMethods
Designer for service development.
Document Conventions
Convention Description
Bold Identifies elements on a user interface.
Narrow font Identifies storage locations for services on webMethods Integration
Server, using the convention folder.subfolder:service.
UPPERCASE Identifies keyboard keys. Keys you must press simultaneously are
joined with a plus sign (+).
Italic Identifies variables for which you must supply values specific to your
own situation or environment. Identifies new terms the first time they
occur in the text.
Monospace Identifies text you must type or messages displayed by the system.
font
{} Indicates a set of choices from which you must choose one. Type only
the information inside the curly braces. Do not type the { } symbols.
| Separates two mutually exclusive choices in a syntax line. Type one of
these choices. Do not type the | symbol.

About This Guide
Convention Description
[] Indicates one or more options. Type only the information inside the
square brackets. Do not type the [ ] symbols.
... Indicates that you can type multiple options of the same type. Type
only the information. Do not type the ellipsis (...).
Documentation Installation
You can download the product documentation using the Software AG Installer.
Depending on the release of the webMethods product suite, the location of the
downloaded documentation will be as shown in the table below.
For webMethods... The documentation is downloaded to...

6.x The installation directory of each product.
7.x A central directory named _documentation in the main
installation directory (webMethods by default).
8.x A central directory named _documentation in the main
installation directory (Software AG by default).
Online Information
You can find additional information about Software AG products at the locations listed
below.
Note: The Empower Product Support Web site and the Software AG Documentation
Web site replace Software AG ServLine24 and webMethods Advantage.
If you want to... Go to...

Access the latest version of product Software AG Documentation Web site
documentation.
http://documentation.softwareag.com

About This Guide
If you want to... Go to...

Find information about product releases and Empower Product Support Web site
tools that you can use to resolve problems.
https://empower.softwareag.com
See the Knowledge Center to:
 Read technical articles and papers.
 Download fixes and service packs.
 Learn about critical alerts.
See the Products area to:
 Download products.
 Get information about product
availability.
 Access older versions of product
documentation.
 Submit feature/enhancement requests.
 Access additional articles, demos, and Software AG Developer Community
tutorials. for webMethods
 Obtain technical information, useful http://communities.softwareag.com/
resources, and online discussion forums, webmethods
moderated by Software AG professionals,
to help you do more with Software AG
technology.
 Use the online discussion forums to
exchange best practices and chat with
other experts.
 Expand your knowledge about product
documentation, code samples, articles,
online seminars, and tutorials.
 Link to external Web sites that discuss
open standards and many Web
technology topics.
 See how other customers are streamlining
their operations with technology from
Software AG.

About This Guide

1 Getting Started with Developer
 What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
 Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
 Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
 What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
 Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
 Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
 Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
 Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

What Is Developer?
Note: webMethods Developer is deprecated and does not support all the features of
webMethods Integration Server 8.2. Software AG recommends the use of
webMethods Designer for service development.
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 Broker/local trigger 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 Storing Services in a Version Control System in
the Software AG_directory\_documentation directory.
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 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.
Important! You can only connect webMethods Developer version 7.1 to a webMethods
Integration Server version 7.1.
To start Developer
1 On the Start menu, click Programs, and then click webMethods.

2 Click webMethods Developer.
Specify the name and

port assignment of a
server...
...and enter a user

account that has
developer privileges.
3 In the Open Session dialog box, complete the following:
In this field... Specify...
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.
Note: The default password for the Developer user account is

isdev.
Uses secure Whether the session will be opened through HTTP or HTTPS. If
connection 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.
4 Click OK.
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 Developer_directory\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 26.
 UDDI Registry tab. You use the UDDI Registry tab to connect to and disconnect from a
UDDI Registry, and to display, filter, and publish Web services. For more information
about this panel, see “The UDDI Registry Tab” on page 29.
 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 31.
 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 31.
 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 33.
 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 35.
Developer main window

The Navigation Panel
displays the contents
of servers, packages,
and folders. The Properties
Panel displays
the properties
The Editor displays for an item.
the controls you use to
examine and edit an
element you have
opened from the
Navigation panel or
Recent Elements tab.
The Results
Panel displays
The UDDI Registry tab the results of a
displays Web services, service’s
if you are connected to execution.
a UDDI Registry. The
Recent Elements Tab
displays the elements
you viewed most
recently.

The Navigation Panel

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 Storing Services in a Version Control System in the
Software AG_directory\_documentation directory.
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 descriptor (WSD). A Web service descriptor is an IS namespace
element that contains the definition of an IS Web service. A WSD
describes either a “provider” or a “consumer” Web service. For more
information about using Web services and the UDDI Registry, see the Web
Services Developer’s Guide.


A provider Web service descriptor (WSD). A Web service descriptor that
contains the definition of a provider IS Web service. A provider Web
service allows an external user to invoke an existing IS service as an
“operation” of the Web service.
A consumer Web service descriptor (WSD). A Web service descriptor that
contains the definition of a consumer Web service. Consumer Web
services are external Web services that can be invoked from within the
local Integration Server.
A Web service connector. A Web service connector is a flow service that
invokes a Web service located on a remote server. Developer
automatically generates a Web service connector when it creates a Web
service descriptor for a consumer Web service. Developer can also create a
Web service connector from an existing WSDL.
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 Broker/local trigger. A Broker/local trigger is trigger that subscribes to and
processes documents published/delivered locally or to the Broker.
For more information about creating Broker/local triggers, see the Publish-
Subscribe Developer’s Guide.
A JMS trigger. A JMS trigger is a trigger that receives messages from a
destination (queue or topic) on a JMS provider and then processes those
messages.
For more information about creating JMS triggers, see Using webMethods
Integration Server to Build a Client for JMS.
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.
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.


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.
Refreshing the Contents of the Navigation Panel

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.
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 40.
The UDDI Registry Tab

Use the UDDI Registry tab to connect to and disconnect from a UDDI Registry. Once you
have opened a UDDI Registry, you can display, filter, and publish Web services in that
registry. Within the UDDI Registry 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 Web services and the UDDI Registry, see the Web Services
Developer’s Guide.
Note: When you select a Web service in the UDDI Registry tab, the editor (the middle
area of the Developer window between the Navigation panel and the Properties
panel) is blank. This is because Developer cannot modify a Web service published to a
UDDI Registry.

UDDI Registry Tab Icons

The following buttons on the UDDI Registry tab toolbar are shortcuts to frequently-used
commands.
Use this
button... To...
Connect to a UDDI Registry while working in Developer.
Disconnect from a UDDI Registry while working in Developer.
Refresh the display of Web services. Equivalent to SessionRefresh UDDI

Registry Display.
Create an expression that filters the contents of the UDDI Registry tab
based on the value of a Web service property.
Remove the filter from the contents of the UDDI Registry tab and
display all the published Web services.
Create a Web service descriptor (WSD) from the Web service selected in
the UDDI Registry tab.
The UDDI Registry tab also contains icons to represent the UDDI Registry, the registered
business entities, and the Web services that have been published to the UDDI Registry.
The following table identifies these icons.

A UDDI Registry Node. Developer displays the URL of the UDDI Registry
to which you are connected next to the registry icon. Below the UDDI
Registry name, Developer displays all of the business entities registered
in that UDDI Registry.
A Business Entity. A business entity is a publisher of Web services to the
UDDI Registry. Below the business entity name, Developer displays the
Web services published by that entity.
A Web service. A Web service is a software application that can be
accessed remotely, using XML- based languages to communicate. From
a Web service or a WSDL, you can create a consumer Web service
descriptor and connector. Developer can invoke the connector to run
the remote Web service. From an existing IS service or WSDL, you can
create a provider Web service descriptor. You can then publish the Web
service descriptor to a UDDI Registry so that the IS service it describes
can be invoked by an external user as an “operation” of the Web service.
For more information about using Web services and the UDDI Registry,
see the Web Services Developer’s Guide.

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 51.
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
If you open In this example, a

an element specification is
from the opened in the
Navigation editor.
panel...
The editor lists
the input and
output fields that
...editing were created for
controls for that this specification.
element are These lists are
displayed in the also referred to
editor. 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
Broker/local 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 26
and “What Is a Lock?” on page 102.
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.

Editor with multiple elements opened

Each opened element
in the editor has its Click to view tabs that are not
own tab. currently visible.
The element’s title bar
displays the element’s
fully qualified name. Click to close the active element
(that is, the element that is
currently displayed).
Some elements have

specialized tabs.
Tip! You can locate the active element in the Navigation panel by using the
EditLocate in Navigation command.
The Properties Panel

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.
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.

Properties panel
Drag to resize the Property
and Value columns.
Name of the item for which properties are

displayed.
Click to collapse the Properties are
list of properties grouped into
beneath a category. categories.
Click to expand the

list of properties
beneath a category.
Description of the
selected property.
Depending on the type of property you select, you edit a property by:
 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
Click a variable
name...
...to view its contents in

the pipeline at this
stage of the service’s
execution.
For more information about service execution results, see Chapter 11, “Testing and
Debugging Services”.
Working in the Developer Window
Moving Between Panels

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
drag-and-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,
UDDI Registry tab, and
Recent Elements tab Click along the left edge of the Developer window.
Show the Navigation
panel, UDDI Registry tab,
and Recent Elements tab
Click along the left edge of the Developer window.
Hide the Properties and
Results panels
Click along the right edge of the Developer window.
Show the Properties and
Results panels
Click along the right edge of the Developer window.
Expand or collapse editor Click on the border between the top of the editor and
details the specialized tabs beneath it.
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, UDDI Registry 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, UDDI Registry
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:
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

Click to hide or Click to display
show the Edit, Test, and
Navigation Detail
panel, UDDI perspectives.
Registry tab
and Recent Click to hide or
Elements tab. show the
Properties and
Results panels.
Click to expand
or collapse
editor details. Drag movable
borders to
resize panels.
Opening, Closing, and Restoring Sessions

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 23.
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 29.

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 40.
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
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

Requirement Default
Minimum number of numeric characters 1
Minimum number of special characters (non-alphabetic and non-numeric 1
characters, such as *. ?, &)
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 built-in
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.


2 Managing Elements in the Navigation Panel
 What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
 Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
 Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
 Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
 Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
 Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
 Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
 Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
 Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
 Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
 Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
 Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
 Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

What Is an Element?
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
Folders, services,
triggers,
specifications,
IS document types,
and IS schemas are
elements.
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 The sections in this chapter
copying, renaming, deleting,
finding, and caching elements
Locking elements Chapter 4, “Locking and Unlocking Elements”
Checking elements in to and out of a Storing Services in a Version Control System in the
third-party version control directory:
repository Software AG_directory\_documentation
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 105.
 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 48.
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 Storing Services in a Version Control
System in the Software AG_directory\_documentation 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...
Confirm before Instruct Developer to notify you before deleting an element

deleting used by other elements, such as flow services, IS document
types, specifications, or triggers.
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.

Select... To...
Prompt before Instruct Developer to alert you when dependents (that is,
updating dependents other elements that use the selected element, such as flow
when services, IS document types, or triggers) exist.
renaming/moving
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.
Update local Instruct Developer to update references when copying and
references when pasting a group of elements that refer to each other.
pasting multiple
If you clear this check box, Developer retains the original
elements
references in the copied elements.
3 Click OK.
For more information about finding dependents, see “Finding Dependents and
References” on page 66.
Notes About Performing Actions on 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 Integration feature (VCS) 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 79.

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:
To... Do this...
Close the active element in the editor On the Window menu, click Close Active
(that is, the element whose tab is Editor.
highlighted)
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 and Document Types” on page 157.
 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

 You cannot copy or move a Web service descriptor element 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 Broker/local 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 webMethods Administering
Integration Server 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.
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 webMethods Administering Integration Server.
Moving and Copying Adapter Notifications and Related Elements

 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 57.
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 OK 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 re-specify 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:
To... Click...
Save changes and then proceed with the move/copy action Save and Proceed
Continue the move/copy action without saving changes Proceed without Save
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.
To... Click...
Move the selected element and update references to Update Usages

dependent elements
Move the selected element in the Navigation panel without Ignore Usages
updating references to dependent elements
Cancel the entire move action Cancel
For more information about dependency safeguards, see “Specifying Dependency

Checking Safeguards” on page 49.
Tip! You can also move elements by clicking and dragging them to their new location.
Renaming Elements
When renaming elements, keep the following points in mind:
 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).
To... Click...
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.
To... Click...
Rename the selected element in the Navigation panel and Update Usages
update references to dependent elements
Rename the selected element without updating references to Ignore Usages
dependent elements
Cancel the entire rename action Cancel

Saving Changes to Elements

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:
To... Do this...
Save changes to the current element On the File menu, click Save.
Save all elements you have edited, on all On the File menu, click Save All Editors.
servers
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.
Deleting Elements
When deleting elements, keep the following points in mind:
 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:
To... Click...
Save changes and then proceed with the delete action Save and Proceed
Proceed with the delete action without saving Proceed without Save
changes
Cancel the entire delete action Cancel
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:
To... Do this...
Delete the element on the Integration Clear the Delete associated Broker
Server but leave the corresponding document type on the Broker check
document type on the Broker box.
Delete the element on the Integration Select the Delete associated Broker
Server and the corresponding document type on the Broker check
document type on the Broker box.
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.
2 Continue or cancel the delete action as follows:
To... Click...
Delete the elements from the Navigation panel (and Continue

therefore break any links to dependent elements)
Cancel the entire delete action Cancel


Finding Elements and Fields

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

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 18, “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.
Results of search for “PO”

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.
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:
To... Do this...
Find fields with the same capitalization as the Select the Match case check box.
text in the Find what field
Find only fields that match the complete word Select the Match whole words check
in the Find what field box.
Find fields that contain the text in the Find what Clear the Match whole words check
field as all or a portion of their name box.
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
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.
Dependent elements
This service is a
dependent of...
...each of these
services.
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, Broker/local 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

The services:receivePO
service is used by...
...this element.
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
Each of these
services is a
reference of
ServiceA.
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 49.
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
service A.
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

The processPO
service uses...
...these elements.
The element in bold

italics does not exist
in the Navigation
panel
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.
Pipeline reference
This variable is a
reference to the
PODocument in the
Navigation panel.
The link between

ONum and num is a
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
This Drop Value

modifier and...
... this Set Value

modifier are pipeline

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.
Inspect Pipeline References dialog box
The getData flow

service contains...
...an invalid reference

in its pipeline to the IS
document type po_doc.
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 Developer.
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 146.


3 Working with Packages
 What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
 Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
 Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
 Publishing and Retracting Information about Integration Server and Trading Networks Assets . 93

What Is a Package?
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 time-
reporting services into a package called “TimeCards.”
On the server, a package represents a subdirectory within the
IntegrationServer_directory\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
webMethods Administering Integration Server.
Package Management
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 webMethods Administering Integration Server.
To... See...
Create a package page 78
Activate a package webMethods Administering Integration
Server
Copy a package to another server page 81
View details for a package page 79

To... See...
Display specific packages by filtering the webMethods Administering Integration
Packages List Server
Document the purpose and function of a page 82
package
View the patch history for a package page 86 and
webMethods Administering Integration
Server
Assign startup, shutdown, or replication page 90
services to a package
Reload the services and files in a package page 83 and
into memory without restarting the server webMethods Administering Integration
Server
Delete the contents of a package page 84 and
Server
Assign a version number to a package page 85 and
Server
Identify packages that must be loaded page 88
before a specific package is loaded (package
dependencies)
Export a package or partial package page 84
Replicate or copy the contents of a package page 81 and
and send (publish) it to other Integration webMethods Administering Integration
Servers Server
Disable a package without deleting the webMethods Administering Integration
package Server
Enable a package that you previously webMethods Administering Integration
disabled Server
Recover services and related files from a webMethods Administering Integration
deleted package Server
Archive a copy of the package (such as for a webMethods Administering Integration
backup copy) Server

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 webMethods Administering Integration Server.
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 IntegrationServer_directory\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 85, “Viewing the Patch History for a Package” on page 86, and
“Identifying Package Dependencies” on page 88.
Optimizing Lock Checking

If the Developer’s Version Control System 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 Developer_directory\config\developer.cnf with a text editor.

2 Add the following properties to the file:
dev.maxServerLockInfoCalls=<value>
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=<value>
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 webMethods Administering Integration Server.
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 88.
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:
IntegrationServer_directory\packages\PurchaseOrders\pub
Tip! An alternate location for package documentation is the

IntegrationServer_directory\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.
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.
Reloading a Package
Sometimes, you need to reload a package on the server to activate changes that have been
made to it outside of Developer or Designer. 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 webMethods Administering 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 66.
 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 webMethods Administering Integration Server.
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.
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 Software AG Software AG Global Support 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
These fields display

information about the
currently installed
patch...
...and these fields

track the 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 The patch numbers included in this release of the package.
Number

Identifying Package Dependencies

If a package needs elements from another package to load before it can load, you must set
up package dependencies. For example, you must 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.
Additionally, you should set up a package dependency if a service uses a document type
from a different package as the input or output signature.
You must 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 must 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:

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.
6 Click OK.
7 On the File menu, click Save.
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.

Removing Package Dependencies

Use the following procedure to remove a package dependency that is no longer needed.
For example, to continue the example from page 88, 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 .
Publishing and Retracting Information about Integration

Server and Trading Networks Assets
You can publish and retract information about Integration Server and Trading Networks
assets to a shared library or registry that resides in CentraSite. By publishing this
information or metadata, you make these assets available to other CentraSite users.
For Integration Server, you can publish and retract information about the following
assets:
 Packages
 Adapter connections
 Adapter notifications
 Adapter services
 Blaze rule services

 Broker/local triggers
 C services
 Document types
 Flat file dictionaries
 Flat file schemas
 Flow services
 IS Schemas
 Java services
 JMS triggers
 .NET services
 Specifications
 Web service connectors
Note: Integration Server publishes/retracts Web service connectors as part of

publishing/retracting a consumer Web service descriptor.
 Web service descriptors

 XSLT services
For Trading Networks, you can publish and retract information about TN document
types.
Note: Metadata about Integration Server cannot be published or retracted explicitly.

However, when you publish metadata for IS and TN assets, metadata about
Integration Server is published as well.
Publishing Metadata about Integration Server and Trading Networks

Assets
Keep the following points in mind when publishing metadata to CentraSite for IS and TN
assets:
 Before you can publish metadata about IS assets and TN document types, your
Integration Server administrator must configure Integration Server to connect to
CentraSite. Refer to webMethods Administering Integration Server for instructions on
configuring Integration Server to connect to CentraSite.
 Because Integration Server defines the connection to CentraSite, every Developer user
that publishes or retracts assets on this Integration Server uses the same set of
credentials.

 To publish metadata about an Integration Server asset, you select the package that
contains the asset whose metadata you want to publish. Developer will publish
metadata for all of the supported assets in the entire package. You cannot select
individual assets for publishing or retracting.
 To publish metadata about Trading Networks assets, you select Trading Networks
Assets. Developer will publish metadata for all TN document types available on the
Integration Server to which Developer is connected.
 Only one metadata operation can run at a time. If you try to submit a publication
request while a retraction or publication request is already running, you will receive
the error Operation already in progress and you will have to resubmit the request
later.
Note: This method of publishing and retracting metadata is deprecated as of

Integration Server version 8.2 SP1. Use Designer version 8.2 SP1 to publish metadata
instead.
To publish information about assets
1 On the Tools menu, select Metadata > Publish > Execute.

2 In the Publish Metadata dialog box:
 To publish metadata about Integration Server assets, select one or more packages.
 To publish metadata about Trading Networks assets, select Trading Networks Assets.
3 If you want Integration Server to automatically publish information about packages
upon which selected packages depend, select the Auto-select package dependencies
check box.
4 Click OK.
To view the status of the publication request, on the Tools menu, click Metadata >
Publish > Status.
Retracting Published Metadata about Integration Server and Trading

Networks Assets
If you later decide you want to remove an asset from CentraSite, you can retract it.
Keep the following points in mind when retracting metadata for IS and TN assets:
 For an Integration Server asset, you must retract the package in which the asset
resides.
 For Trading Networks assets, you must retract all TN document types.
 You cannot retract a published asset that is referenced by another published asset
until the asset that established the reference is retracted. For example, suppose that
you publish a process (processA), that uses an IS service (serviceA). Then, you

publish the package (packageA) that contains serviceA. Because processA depends
on an asset in packageA, you can only retract packageA (and any of its contents) after
you retract processA. If you change processA so that it no longer references serviceA
and republish processA, you can retract packageA.
 If a published IS asset is in pending state in CentraSite, retracting the package that
contains the IS asset results in an orphaned asset in CentraSite. For example, suppose
that you published a package containing an IS service to CentraSite. If you change the
life cycle state of the IS service asset to "Deploy" and then retract the package while
the state change is pending, the IS service asset is not deleted when the package is
retracted. The IS service asset becomes an orphaned asset in CentraSite.
 Only one metadata operation can run at a time. If you try to submit a publication
request while a retraction or publication request is already running, you will receive
the error Operation already in progress and you will have to resubmit the request
later.
To retract information about assets
1 On the Tools menu, select Metadata > Retract > Execute.

2 In the Retract Metadata dialog box:
 To retract metadata about Integration Server assets, select one or more packages.
 To retract metadata about Trading Networks assets, select Trading Networks Assets.
3 Click OK.
4 To view the status of the retraction request, on the Tools menu, click Metadata >
Retract > Status.
Usage Notes for Publishing/Retracting IS Assets

Keep the following information in mind when publishing and retracting metadata for IS
assets.
 Uninstalling Integration Server can cause any published IS assets to become
unreferenced, or orphaned. Retract any published IS assets before uninstalling the
Integration Server that contains those assets.
 CentraSite only establishes the “Uses” relationship between the IS Service Interface
asset created for a consumer Web service descriptor and the Service asset created for a
web service if the Service asset exists in CentraSite before you publish the consumer
Web service descriptor.
If you create the web service asset in CentraSite by importing its WSDL after
publishing the consumer Web service descriptor, republish the consumer Web service
descriptor to establish the “Uses” relationship between the IS Service Interface asset
created for the Web service descriptor and the Service asset created for the web
service.

 To establish the correct relationships between Web service descriptors created from
WSDL documents and the CentraSite Service asset, use the New wizard in Designer
to create the Web service descriptor and select CentraSite as the source location. If you
create a Web service descriptor from a WSDL in CentraSite through the UDDI
registry or directly from a file or URL, the “Uses” and “Implements” relationships
will not be established between the Web service descriptor and the CentraSite service
asset.
 If you intend to change the compatibility mode of a Web service descriptor for which
you published metadata to CentraSite, first retract metadata for the Web service
descriptor. Next, change the compatibility mode. Finally, republish metadata for the
Web service descriptor to CentraSite.
For more information about Web service descriptors and compatibility mode, see the
Web Services Developer’s Guide.
 Each asset in CentraSite has a “Deployed On” property that identifies each
Integration Server from which an asset with that name has been published. However,
the Integration Servers might have published different versions of the same asset or
completely different assets that happen to have the same name. In CentraSite, it will
appear as if both Integration Servers published the exact same asset. CentraSite will
maintain the asset that was most recently published.
For example, suppose that Integration Server1 publishes a service named “myService”.
CentraSite creates an IS service asset with the name “myService” and a “Deployed On”
property value of Integration Server1. Later, Integration Server2 also publishes a
service named “myService” but the service published by Integration Server2 is not
identical to the service published by Integration Server1. CentraSite will update the IS
service asset to represent the “myService” service published Integration Server2.
CentraSite also updates the “Deployed On” property value to be: Integration Server1,
Integration Server2. CentraSite indicates that both Integration Servers published an
identical asset when, in fact, they did not.
When an Integration Server retracts an asset, CentraSite removes that Integration
Server from the “Deployed On” property for the CentraSite asset. If the asset is not
deployed on another Integration Server, CentraSite removes the asset. If the asset is
deployed on another Integration Server, the asset remains in CentraSite. The content
of the CentraSite asset will be the asset that was most recently published. This might
result in a CentraSite asset whose content does not represent the IS asset that was
published by the Integration Server listed in the “Deployed On” property.
To continue the above example in which Integration Server1 and then Integration
Server2 published different versions of services named “myService,” if Integration
Server2 retracts “myService, CentraSite removes Integration Server2 from the
“Deployed On” property value. However, the content of the “myService” asset in
CentraSite represents the “myService” asset published by Integration Server2 because
Integration Server2 published the asset most recently. This results in CentraSite
indicating that the “myService” asset published by Integration Server2 is deployed on
Integration Server1.

Checking the Status of Publication and Retraction Requests

After you submit a request to publish or retract information about Integration Server or
Trading Networks assets, you can check the status of the request.
To check the status of a publication request
 On the Tools menu, select Metadata > Publish > Status.
To check the status of a retraction request
 On the Tools menu, select Metadata > Retract > Status.
Status Information for Publication and Retraction Requests

For both publication and retraction requests, Developer displays a status screen that
contains the following information:
Field Description
Name If a package was selected for metadata publication or retraction, this

field displays the package name.
If Trading Networks Assets was selected for metadata publication or
retraction, this field displays TN Assets.
Assets The total number of assets being processed. This value will not be
displayed until all the assets for the given package or all TN document
types have been counted.
Status One of the following states:
Starting Integration Server is starting the request. This is
always the initial state when a request is submitted.
Counting Integration Server is counting the number of assets in
the package or the number of TN document types.
Counted Integration Server has completed counting the number
of assets in the package or the number of TN
document types. The total number is displayed in the
Assets column.
Extracting Integration Server is extracting the metadata for
selected assets.

Field Description
Publishing For publication requests only: Integration Server is

sending the metadata to CentraSite.
Complete For publication requests, Integration Server has
finished sending the metadata to CentraSite.
For retraction requests, Integration Server has finished
retracting the metadata from CentraSite.
The following summary fields are displayed at the bottom of the screen:
Field Description
Status The overall status of the most recent publication or retraction

request.
Assets The total number of assets processed in the most recent publication
or retraction request.
Duration The time (in hh:mm:ss) spent executing the most recent publication
or retraction request.

4 Locking and Unlocking Elements
 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

 Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
 Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Basic Concepts
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 Storing Services in a Version Control System in the
Software AG_directory\_documentation 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
Locked by another user No Contact the user to unlock.
Locked by the system No Contact the server

administrator to unlock.
How Do I Know Who Has an Element Locked?

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 107 and “Viewing an Element’s Corresponding Server Files” on
page 112.
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 104.
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 108.
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 113.
Locking Elements
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 105.
 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 105.
 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 113.
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 112. 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.
Note: System locking is not supported if you are running Integration Server as root on a
Unix system.
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 108.
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.
Unlocking Elements
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 105.
 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
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 111.
 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 112.
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 113.
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 113.
Where is the lock information stored (such as names of elements that are locked, when they were
locked, etc.)?
The information is stored internally in Repository version 4, and in the VCS repository, if
you are using VCS.
Important! Do not perform development work in a clustered environment. Basic

namespace locking and the WmVCS package are not supported across Integration
Servers in a cluster.
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).
5 Assigning and Managing Permissions
 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

 Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
 Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
 How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Basic Concepts
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 or a Web service descriptor.
For more details about these types of access, see webMethods Administering 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 122.
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
webMethods Integration Server
1
Client Purch:SubmitPO
Purch:SubmitPO
2
INVOKE Purch:LogPO Purch:LogPO
3
INVOKE Purch:CreditAuth Purch:CreditAuth
4
INVOKE Purch:SendPO Purch:SendPO
Stage Description
1 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.
2 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.
Stage Description
3 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.
4 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 121.
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.
Am I Required to Use ACLs?

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 webMethods Administering Integration Server.
How Do I Create an ACL?

You create ACLs using the Integration Server Administrator. For details, see webMethods
Administering Integration Server.
Assigning ACLs to Elements

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 webMethods
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 122.
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

To
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 webMethods
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 122.
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 webMethods Administering Integration Server.
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
An element can have

different ACLs assigned for
each level of access.
Field / Button Description

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 and Web service descriptors.
Field / Button Description

Enforce  When top-level service only. The Integration Server performs ACL
execute 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.
ACLs and Inheritance

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 webMethods Administering Integration Server.
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
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  Allowed. The user group(s) that have been explicitly allowed to
Association for access the packages, folders, services, or other elements
‘[ACL]’ 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.
Resulting Users The names of users that the ACL authorizes, given the current
for ‘[ACL]’ 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 webMethods
How ACLs Affect Other Developer Features
ACLs and Locking

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 webMethods Administering Integration Server.
 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 113 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.
6 Building Flow Services
 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

 A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
 Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
 Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
 Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
 Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
 Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
 Assigning Universal Names to Services and Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . 157
 Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
 Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Basic Concepts
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

Client application Purch:SubmitPO
Purch:SubmitPO
invokes
Purch:SubmitPO...
INVOKE Purch:GetOrders 1
INVOKE Purch:LogOrder 2 ...which performs a

sequence
INVOKE Purch:CreditAuth 3 of four services
INVOKE Purch:PostPO 4
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 with the
webMethods Integration Server, 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
Integration Server.
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.
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
Purch:SubmitPO
Purch:SubmitPO
INVOKE Purch:GetOrders
A LOOP step LOOP PurchaseOrders

repeats a set
of INVOKE Purch:LogOrder
flow steps
INVOKE Purch:CreditAuth
A BRANCH step BRANCH AuthOK

selects a specified
flow step for INVOKE Purch:PostPO
execution
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 177.
Data-Handling Steps
MAP 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 205.
Control Steps
BRANCH 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 180.
LOOP 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 198.
REPEAT 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 190.
SEQUENCE 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 196.
EXIT 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 202.
See Appendix 17, “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?

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.
The pipeline holds the input and output for a flow service
Services in a flow get Flow Service The Pipeline
their input from and
place their output in input ONum:46-77135
the pipeline.
Name:Kings Sport
INVOKE Purch:LogPO
Phone:201-887-1544
output TNum:128824993554
input Acct:128824993554
Total:5732.78
INVOKE Purch:CreditAuth
Qty:20
output AuthNum:TW99123554
input Date:04/04/99
INVOKE Purch:ConvertDate Item:PK8801-NS
output OrderDate:19990404
input Ship:UPS Ground
Terms:30N
INVOKE Purch:SendPO
Freight:65.00
output 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 Output
Name Data Type Name Data Type
AcctNum String AuthCode String
OrderTotal String
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).
A Process Overview
Building a flow service is a process that involves the following basic stages:
Stage 1 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.
Stage 2 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”.
Stage 3 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 137.
Stage 4 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”.
Stage 5 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 145.
Stage 6 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 142 or refer to
the Dynamic Server Pages and Output Templates Developer’s Guide.
Stage 7 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 78.
 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 47. For
information about ACL permissions, see Chapter 5, “Assigning and Managing
Permissions”.
Once the package and folder are in place, use the FileNew command to start the process
of creating a new service. For details, see “Creating New Elements” on page 47.
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 Automatically generate a flow service that invokes the loadXMLNode
an HTML Page 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 Load and Query Services Developer’s Guide.
Receive an XML Automatically generate a service that receives an XML node as
Document 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.
Inserting Flow Steps

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 19, “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 208.
 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 19, “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 with a Broker/local trigger or a JMS trigger,
make sure the input signature conforms to the requirements for each of those trigger
types. For more information about creating Broker/local triggers, see the Publish-
Subscribe Developer’s Guide. For more information about creating JMS triggers, see
Using webMethods Integration Server to Build a Client for JMS.
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 208.
 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 19, “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.
Input/Output tab
Define the flow

service’s input
parameters
on this side...
...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 137.
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 IntegrationServer_directory\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

IntegrationServer_directory\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“).
5 Do one of the following:

 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
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 72.
 Execution locale of a service. You can set the type of locale in which the Integration
Server executes at run time.
 Creating a URL alias for a service. You can create an alias for the path portion of the URL
used to invoke a service.
 Saving and restoring of the pipeline. You can save the pipeline or restore a previously
saved pipeline 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 need to have its session
object maintained when it is finished executing. For best performance, use stateful
services if your Integration Server receives requests from repeating clients. The client can
connect to Integration Server, be authenticated just once, and then issue many service
invocations during the same session. Use stateless services if clients typically send a
single invocation request to Integration Server at a time. Using a stateless service
prevents the creation of sessions that will sit unused, taking up resources in Integration
Server.
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: The service-caching feature described in this section is not related to the caching
capabilities provided by Ehcache. Service caching enables you to easily cache the
results of a service. If you want to cache specific objects in the pipeline or you need
more advanced caching capabilities, use the caching services in the pub.cache folder.
For more information about these caching services, see the webMethods Integration
Server Built-In Services Reference. For more information about how Integration Server
uses Ehcache, see webMethods Administering Integration Server.
Note: Caching is only available for data that can be written to Repository version 4.
Because nodes cannot be written to Repository version 4, 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
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

3 In the Runtime category of the Properties panel, do one of the following to specify the
Execution Locale property:
Select... To...
[$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.
[<ISO code>] <Language> 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.
Setting Up URL Aliases for Services

Using a URL alias for a service is convenient because it saves you from specifying full
path information for the service every time you have to enter the service URL. Also, if a
service URL has an alias, you can update the path information for the service without
having to modify the alias. Another benefit to using aliases is the added security; they
prevent the external world from seeing the service names in a URL.
When you create a URL alias, you specify an alias for the path portion of the URL used to
invoke a service. The path portion of the URL consists of the invoke directive and the
fully-qualified service name.
You can create URL aliases for services from Developer and from Integration Server.
Create an alias from Integration Server if you want to assign aliases to resources other
than services, or if you want to assign more than one alias to a resource. See webMethods
Administering Integration Server for more information.
Example
1 2
http://IS_server:5555/invoke/folder.subFolder/serviceName
Item Description
1 Identifies the webMethods Integration Server on which the service you want
to invoke resides.
2 Specifies the path portion of the URL, which includes the invoke directive
“invoke.” The path also identifies the folder in which the service resides and
the name of the service to invoke. Separate subfolders with periods. These
fields are 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.
To create an alias for a service URL, use the HTTP URL alias property in the Properties
panel. When you specify an alias in the HTTP URL alias property and save the service,
Integration Server creates an HTTP path alias for the service URL. The target of the alias
is the path that invokes the service. The path alias is the string that you entered in the
property field.
For example, if the name of the service is folder.subFolder:serviceName, then the path to
invoke the service is invoke/folder.subFolder/serviceName. If you enter "test" in the HTTP
URL alias property and save the service, then the two following URLs will point to the
same service:
http://IS_server:5555/invoke/folder.subFolder/serviceName
http://IS_server:5555/test
When creating a path alias for a service, keep the following in mind:
 When you add, edit, or delete an HTTP URL alias property in a service, the property is
automatically updated on the Integration Server when the service is saved.
 Integration Server stores the HTTP URL alias information in the node.ndf file of the
service. Because the property is encoded in the node.ndf file, it is propagated across
servers through package replication.
 URL aliases for services are saved in memory on the Integration Server. The server
checks for URL aliases before processing HTTP requests.
 When specifying the alias URL, you must spell it exactly as it is defined on the server.
Alias URLs are case sensitive.
Creating a Path Alias for a Service

Use the HTTP URL alias property in the Properties panel to create a path alias to use when
invoking the service in a URL.
To create an alias for a service URL

3 In the Runtime category of the Properties panel, next to the HTTP URL alias property,
enter an alias string for the URL that will invoke the service.
Important! Do not use reserved characters in the URL alias string. Alias strings that
contain reserved characters are invalid and will not work.
Using the Pipeline Debug Property

You use the Pipeline Debug property to save and restore the pipeline at run time. The
ability to save and restore the pipeline for a service is helpful when you are testing and
debugging the service.
Important! The Pipeline Debug options you select can be overwritten at run time
by the value of the watt.server.pipeline.processor property, set in the server
configuration file. This property specifies whether to globally enable or disable
the Pipeline Debug feature. The default enables the Pipeline Debug feature on
a service-by-service basis. For more information on setting properties in the
server configuration file, see webMethods Administering Integration Server.
For more information about testing and debugging services and to learn about other tools
and methods you can use, see Chapter 11, “Testing and Debugging Services”.
Using the Pipeline Debug Property to Save the Service Pipeline

You use the Pipeline Debug property to specify whether or not you want the server to
automatically save the pipeline for the service at run time. If you set Pipeline Debug to Save,
webMethods Integration Server saves the entire contents of the pipeline to a file just
before the service executes.
To save the service pipeline

3 In the Runtime category of the Properties panel, next to the Pipeline Debug property,
select Save.
When you run the service, the contents of the pipeline are saved to a file on
webMethods Integration Server. The file is saved as folderName.serviceName.xml in the
IntegrationServer_directory\pipeline directory. If the file does not exist, the service
creates it. If the file already exists, the service overwrites it.
Using the Pipeline Debug Property to Restore the Service Pipeline

You use the Pipeline Debug property to specify whether or not you want the server to
automatically restore the pipeline for the service at run time. When you restore the
service pipeline using this property, webMethods Integration Server either merges or
overwrites the pipeline using the contents from a previously saved pipeline file.
To restore the service pipeline

3 In the Runtime category of the Properties panel, next to the Pipeline Debug property,
select one of the following options:
Select... To...
Restore (Override) Restore the pipeline from a file when the service executes.
Restore (Merge) Merge the pipeline with one from a file when the service
executes.
When this option is selected and the input parameters in the file
match the input parameters in the pipeline, the values defined
in the file are used in the pipeline. If there are input parameters
in the pipeline that are not matched in the file, the input
parameters in the pipeline remain in the pipeline.
When the service executes, the server loads the pipeline file,
folderName.serviceName.xml, from the IntegrationServer_directory\pipeline directory.
Note: The server will throw an exception at run time if the pipeline file does not
exist or cannot be found. To learn how to save the service pipeline using the
Pipeline Debug property, see “Using the Pipeline Debug Property to Save the
Service Pipeline” on page 153.
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 service 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 service
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 155.
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 155.
Assigning Universal Names to Services and Document Types

Every service and document type on a webMethods Integration Server has a universal
name in addition to its regular webMethods name. A universal name is a unique public
identifier used to reference a service or document type on a 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 or
document type 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 or document type’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. 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 “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 or document
type 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 or
document type 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 or document type resides on the
Integration Server.
 The local name is the unqualified name of the service or document type.
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 or document type whose universal name you want to assign, edit, or
view.
2 In the editor, click the service’s or document type’s title bar to give the service or
document type the focus.
3 If you want to assign or edit a 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 or
document type. You must specify a valid absolute URI.
Local name A name that uniquely identifies the service or document type
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.
Note: Many webMethods users use the unqualified portion of the

service name or document type as the local name.
Note: If you move a service or document type, or a folder containing a service or

document type, Developer retains the service’s or document type’s explicit universal
name. If you copy a service or document type, or a folder containing a service or
document type, Developer does not retain the explicit universal name.
To delete a universal name
1 Open the service or document type whose universal name you want to delete.
2 In the editor, click the service’s or document type’s title bar to give the service or
document type the focus.
3 In the Universal Name category of the Properties panel, clear the settings in the
Namespace name and Local name fields.
Configuring Service Auditing

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 service log.
The service log can contain entries for service start, service end, and service failure. The
service 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 service log. If the service log is stored in 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 identity 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 service 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 service log.
 Whether to include a copy of the service input pipeline in the service log.
Audit properties for a service
Specifies if a service
generates audit
data. Specifies when a
service generates
Specifies when to audit data during
include the pipeline execution.
in the service log.
Keep in mind that generating audit data can impact performance. The Integration Server
uses the network to send the audit data to the service log and uses memory to actually
save the data in the service 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.
Note: The service log can be stored in 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 service
log whether it is in a flat file or a database. If the service log is in 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 service log exists. For more information about the service log, see
the webMethods Audit Logging Guide.
Enabling Auditing for a Service

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 service 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 15, “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 service 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 The service generates audit data when the service finishes executing,
success regardless of whether it ends because of success or failure. The service
log will contain an entry for every time the service finishes processing.
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.
Error, success, The service generates audit data when it begins executing and when it
and start finishes executing. When the service executes to completion, the
service 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 service log using webMethods Monitor, the
service 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.
In both situations, if service execution began but did not complete, the
service 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 service 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.
Including the Pipeline in the Service Log

When you configure service auditing, you can specify whether the server should include
a copy of the service’s input pipeline in the service log. If the service 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 service log.
The pipeline data saved in the service 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 Service 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.
Service log settings for ServiceA

The service 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.
The service 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 service log will
not contain a copy of the input pipeline.
Note: Including the pipeline in the service log is more beneficial when the service log
is stored in a database. The Integration Server can save the pipeline to a flat file
service 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 service 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 service log. Select this option if you are using a flat file
for the service 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 service log.
On errors only The Integration Server saves a copy of the input pipeline to the service
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 service log.
Include pipeline Description
Always The Integration Server saves a copy of the input pipeline to the service
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 service 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.
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 service 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 service 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.
Service Auditing Use Cases

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 service 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
In error auditing, you use the service log to track and reinvoke failed services. To use the
service 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 service log.
With webMethods Monitor, you can only reinvoke top-level services (those services
invoked directly by a client or by a Broker/local 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 top-level service and it fails.
To make sure the service 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
Note: If you want to be able to audit all failed invocations of
this service, select Always.
Include pipeline On errors only
Log on Error only
To use the service log for error auditing, store the service log in a database.
Service Auditing
When you perform service auditing, you use the service log to track which services
execute successfully and which services fail. You can perform service auditing to analyze
the service log and determine how often a service executes, how many times it succeeds,
and how many times it fails. To use the service log for service auditing, services need to
generate audit data after execution ends.
To make sure the service log contains the information needed to perform service
auditing, select the following Audit properties.

Include pipeline Never
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.
Log on Error and success
To use the service log for service auditing, you can store the service log in either a flat file
or a database.
Auditing for Recovery

Auditing for recovery involves using the service 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 service log needs to contain an entry for each service invoked by a client
request or a trigger. The service log also needs to contain a copy of each service’s input
pipeline.
To use the service log to audit for recovery, select the following Audit properties.

Include pipeline Always
Log on Error and success
To use the service log to audit for recovery, store the service log in a database.
Auditing Long-Running Services

If a service takes a long time to process, you might want to use the service log to verify
that service execution started. If the service 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 service
log includes a copy of the service’s input pipeline. Make sure that you select options that
will provide the service 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 service log exists. A
service log can be stored in 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 161.
4 For Include pipeline, select an option to indicate when the Integration Server should
include a copy of the input pipeline in the service 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 Service Log” on page 163.
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 161.
Important! The options you select in the Audit category can be overwritten at run time
by the level set for the Service Logger in Integration Server. View the Service Logger
level on the Setting > Logging > View Service Logger Details page of Integration Server
Administrator.
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.
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
Printing a Flow Service

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
Input/Output
parameters
Body of the flow
Details of each
flow step
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.
7 Inserting Flow Steps
 What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

 Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
 The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
 The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
 The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
 The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
 The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
 The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
 The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
What Is a Flow Step?

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).
Displaying the steps in a flow service
Flow steps are

displayed in
the editor.
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 177
MAP step 205
BRANCH step 180
To insert a/an... Click this button... For more information, see page...
LOOP step 198
REPEAT step 190
SEQUENCE step 196
EXIT step 202
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 BRANCH step has children and one of its children is a BRANCH step,
which has its own set of children.
Child steps are indented beneath their parent step
These steps are

“children” of the
BRANCH step.
This step is a “child”

of the LOOP 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.
Properties of a flow step
Use the
Properties
panel to view
and set the
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 180 and “The EXIT Step” on page 202
for additional information about this use of the label property.
For a complete description of the properties associated with each flow step, see
Appendix 17, “webMethods Flow Steps”.
The INVOKE Step

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 284.
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 Services Reference.
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,
Integration Server issues a FlowTimeoutException and execution
continues with the next step in the service.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols. For
example, %expiration%. The variable you specify must be a String.
If you do not need to specify a time-out period, leave Timeout
blank.
For more information about how Integration Server handles flow
step timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter
in webMethods Administering Integration Server.
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
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.
For information about validating output, see “Performing
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 213.
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.
The BRANCH Step

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:
 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.
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 181.
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 181.
Simple BRANCH step that branches on a switch value
Each conditional
step has a label
that matches the
value that causes
it to execute.
The Switch property of the

BRANCH step specifies the
name of the variable that
acts as the switch.
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 18, “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 through the BRANCH
If PaymentType is
“COD,” execution
will fall through this
BRANCH step.
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 184.
 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 184.
 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 185.
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 20, “Conditional Expressions”.
Simple BRANCH step that branches on an expression
Each
target step
has an
expression
as the
label.
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 185.
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 Leave the Label property blank (empty). At run time, the BRANCH
string 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.
BRANCH that contains target steps to match null values or empty strings
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.
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 default step is set to $default
The first two target

steps handle credit
card and corporate
account
payments...
...and the
$default target
step handles the
rest.
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.
Using SEQUENCE as the Target of a BRANCH

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.
Use a SEQUENCE step as the target for a multi-step alternative
Create a SEQUENCE
for each multi-step
alternative...
Define a multi-step alternative in a SEQUENCE
...and then specify the

appropriate series of
flow steps as children
beneath each
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 196.
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.
Integration Server issues a FlowTimeoutException and execution
continues with the next step in the service.
If you want to use the value of a pipeline variable for this property,
type the variable name between % symbols. For example,
%expiration%. The variable you specify must be a String.

blank.
For more information about how Integration Server handles flow
step timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter in
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 184.
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 202.
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
object value
Example for Boolean object true
Example for Integer object 123
Any string fitting the criteria specified by the regular A regular
expression expression
Example /^REL/
An empty string A blank field
A null value $null
Any unmatched value (that is, execute the step if the value $default
does not match any other label)
d Set other properties as needed.
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

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
This INVOKE step is

repeated up to 10
times if it fails at run
time.
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 re-
executes 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. The variable you
specify must be a String.
 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
step inserted.


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

Integration Server issues a FlowTimeoutException and
execution continues with the next step in the service.
example, %expiration%. The variable you specify must be a
String.
blank.
For more information about how Integration Server handles
flow step timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter
in webMethods Administering Integration Server.
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 180 or “The EXIT Step” on page 202.
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%). The variable you specify must be
a String.
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.
property, type the variable name between % symbols (for
example, %waittime%). The variable you specify must be a String.
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
step inserted.


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.

String.
blank.
watt.server.threadKill.timeout.enabled configuration
parameter in webMethods Administering Integration Server.
Label An optional name for this specific 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 180 or “The EXIT Step” on
page 202.
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%). The variable you specify must
be a String.
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.
property, type the variable name between % symbols (for
example, %waittime%). The variable you specify must be a
String.
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 186.
 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 FAILURE
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.
If you want the server to… Set “Exit on” to…
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.
Exit the sequence when any step in the sequence succeeds. SUCCESS
(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 DONE
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.
Note: Rollback operations are performed on the first level of the pipeline only. That is,
first-level 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 LOOP Step

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.
Simple LOOP step
The body of the

loop must be
indented beneath
the 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
The entire
LOOP step
is a child of the
outer LOOP.
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.
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
The LOOP step

executes once for
each member of the
array specified in
Input array.
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…

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

String.
blank.
watt.server.threadKill.timeout.enabled configuration
parameter in webMethods Administering Integration Server.
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 180 or “The EXIT Step” on
page 202.
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.
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 Step

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.
Use the EXIT step to exit the nearest ancestor LOOP step
This LOOP
exits when....
...CreditCardType
is null...
...or empty.
To build an EXIT step

1 When 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.


Label An optional name for this specific step, or a null, unmatched, 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 180.
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.

$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%).
The variable you specify must be a String.
This property is not used when Signal is set to SUCCESS.
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.
 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”.
8 Mapping Data in a Flow Service
 What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

 What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
 Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
 Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
What Is Data Mapping?

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 279.
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 235.
 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 a pipeline variable to a service variable. The Link modifier lets you
Link 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 213.
Drop a variable from the pipeline. The Drop modifier removes
extraneous variables from the pipeline. For information about
Drop
using this pipeline modifier, see “Dropping Variables from the
Pipeline” on page 231.
Assign a value to a variable. The Set Value modifier “hard codes” a
value for a variable. For information about this pipeline modifier,
Set Value
see “Assigning Values to Pipeline Variables” on page 227.
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.
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
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.
4 Scroll or resize the Pipeline tab to display the portion of the pipeline you want to view
as HTML.
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

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 213
Linking variables of different data types 220
Linking to and from array variables 222
Deleting links between variables 225
Applying conditions to links between variables 225
Assigning values to pipeline variables 227
Dropping variables from the pipeline 231
Adding variables to the pipeline 232
Searching for variables in an editor tree 64
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.
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
Pipeline variables
are automatically
linked to service
variables of the
same name.
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.
Linking the pipeline to service input
When a pipeline
variable name is
different from the one
used by the service,
use the Link modifier
to connect them.
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.
Developer automatically
adds a service’s output
variables to the pipeline and
implicitly links them.
When you link variables in the pipeline, keep the following points in mind:
 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 217.)
 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 222. For more information about placing conditions on links between
variables, see “Applying Conditions to Links Between Variables” on page 225.
 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 222.
 If you want to place a condition on the execution of the link, see “Applying
Conditions to Links Between Variables” on page 225.
 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.
Step 1: The value of String1 is set to “original value”
The value of String1 is set

to “original value”.
Step 2: Document1 is linked to Document2
Document1 is linked to
Document2. After the link
executes, the value of
Document2 is a reference to
the contents of Document1.
Step 3: The value of String1 is changed to “modified” after the link executes
The value of String1 is

changed to “modified”.
This action changes the
value of the string in
Document2 as well.
When this flow service executes, it returns the following results.
Results of flow service
The String1 in Document1

and the String1 in
Document2 have the same
value because Document1
was copied to Document2
by reference.
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 441.
 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 444.
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 233. 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 an index value when linking to or from an array variable
You can specify the

index for the element
in buyerAddress that
you want to link to
each field in address.
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 220.
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 216.
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
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
Use the Properties

panel to view or
create a condition
for the link.
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 180.
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 216.
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 20, “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 318.
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).
Hardcoding the value of a variable
You use the Set

Value modifier to
assign a value to 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
Specify the value that

you want the server to
assign to this variable
at run time.
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.
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
Enclose the variable
name in % symbols...
...and the select the

variable-substitution
option.
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.
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.
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

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
Integration Server 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 Services Reference.
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 240.
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.
For information about validating transformers, see “Validating
Input and Output for Transformers” on page 240.
5 Click OK.
For information about debugging transformers, see “Debugging Transformers” on
page 243.
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 237.
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 49.
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 312.
 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 313.
 Disable a transformer so that it does not execute at run time. For more information
about disabling transformers, see “Disabling Transformers” on page 317.
Note: You can also use the Pipeline debug property when testing and debugging the
flow service to view the activity of a transformer. The Pipeline debug property
enables you to easily 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.
9 Creating IS Schemas, IS Document Types, and
Specifications
 Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

 Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
 Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
9 Creating IS Schemas, IS Document Types, and Specifications
Creating an IS Schema
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 <lineItem> element must consist of the <itemNumber>,
<size>, <color>, <quantity>, and <unitPrice> 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 <quantity>
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 251.
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.
Schema editor
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 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.
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 <schema> 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 <element> 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 <element> 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 <any> 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 <any> 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
<attribute> 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 <anyAttribute> declaration in
an XML schema.
Because an <anyAttribute> declaration does not specify an attribute name,
the schema browser uses 'Any' as the name of the attribute.
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
<simpleType> 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.
Symbol Description
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 <complexType> 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
<sequence> 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 <choice> 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 <all> 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.
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 an
element
declaration...
... the schema details

area displays
information about that
element.
When you select a simple type definition, the schema details area looks like the following:
Schema details area for a simple type definition
If you select a simple

type definition...
... the schema details

area displays fields for
viewing/editing the
simple type.
About Schema Domains

Each IS schema on Integration Server belongs to a schema domain. A schema domain is a
named collection of IS schemas.
Within each schema domain, the schema components such as element declarations,
attribute declarations, type definitions for an XML namespaces must be unique.
However, more than one schema domain can contain the same schema components for
an XML namespace. This allows Integration Server to maintain multiple IS schemas for
the same XML namespace.
If you want to maintain alternate definitions of schema components for an XML
namespaces, assign the IS schemas that contain those components to different schema
domains.
Integration Server contains a default schema domain in which any IS schemas created
prior to version 8.0 reside. You can place new schemas in the default schema domain or
you can specify a different schema domain. A schema domain name is any string that is a
valid name of an element in Integration Server. For more information about naming
restrictions for Integration Server elements, see “Guidelines for Naming Elements” on
page 48.
When Integration Server consumes a WSDL document to create a web service descriptor,
Integration Server places any generated IS schemas in a unique schema domain for that
Web service descriptor.
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:
Developer_directory\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 47.
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 Create an IS schema based on an XML schema definition.
Schema
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 Under Schema domain, specify the schema domain to which the generated IS schema
will belong. Do one of the following:
 To add the IS schema to the default schema domain, select Use default schema
domain.
 To add the IS schemas to a specified schema domain, select Use specified schema
domain and provide the name of the schema domain in the text box. A schema
domain name must be a string that is a valid name of an element in Integration
Server. For more information about naming restrictions for Integration Server
elements, see “Guidelines for Naming Elements” on page 48.
For more information about schema domains, see “About Schema Domains” on
page 251.
9 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 23, “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 507.
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 <include> 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
<import> 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 <redefine> to include and then redefine type
definitions, model groups, and attribute groups from an external XML schema in the
same namespace.
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
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.
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 255.
 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 255.
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 483.
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 47.
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.
5 Click Finish.
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 details about the _env field, see “The Envelope Field” on page 267.
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 272. For information about applying constraints, see
“Applying Constraints to Variables” on page 279.
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 279.
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.
Points to Consider for All Sources

Keep the following point 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
document type.
Points to Consider When Using a DTD As the Source

Keep the following point in mind when creating 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:
<?xml version="1.0" encoding="8859-1" ?>
Points to Consider When Using an XML Schema As the Source

Keep the following points in mind when creating an IS document type from an XML
schema:
 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.
 You can specify the namespace prefixes that you want to use in the IS document type.
The prefix you assign must be unique and must be a valid XML NCName as defined
by the specification http://www.w3.org/TR/REC-xml-names/#NT-NCName.
By default, 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”.
 You can select one or more global element declarations as the root node for the IS
document type. Integration Server includes all of the selected elements in the same IS
document type. The selected elements appear as top-level fields in the generated IS
document type.
 When the XML schema contains only one reference to a particular global element of
complex type, you can specify whether Integration Server represents the element
reference with one of the following:
 A document defined inline. Integration Server inserts a document field for the
global element in the IS document type. The document field contents correspond
to the content model of the global element. This is the default.
 A document reference. Integration Server inserts a document reference to an IS
document type whose content corresponds to the content model of the global
element.
Note: Integration Server uses document references automatically if the XML

schema contains multiple references to a particular global element.
 Integration Server always expands element references to element declarations of

simple type inline.
 Integration Server can create separate IS document types for named complex types or
expand document types inline within one document type. For more information, see
“Expanding Complex Document Types Inline” on page 260.
 Integration Server generates a separate IS document type for any referenced complex
type and generates an IS document type for any types derived from the referenced
complex types.
 Integration Server can create one field for a substitution group or create fields for
every member element in a substitution group. For more information, see
“Generating Fields for Substitution Groups” on page 262.
Expanding Complex Document Types Inline

Integration Server processes complex types from an XML schema in one of two ways,
depending on an option you select when you create a new IS document type. One way is
to expand the complex type as an “inline” document type in the editor. The other way is
to generate a separate IS document type for each complex type in the schema, with
references to those document types.
Example XML Schema
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://usecases/xsd2doc/01"
xmlns:uc="http://usecases/xsd2doc/01" >
<xsd:element name="eltA" type="uc:documentX" />
<xsd:complexType name="documentX">
<xsd:sequence>
<xsd:element name="eltX_E" type="xsd:string" />
<xsd:element name="eltX_F" type="uc:documentY" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="documentY">
<xsd:sequence>
<xsd:element name="eltY_G" type="xsd:string" />
<xsd:element name="eltY_H" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
If you select the option to expand complex types inline, the schema processor generates
the document type as follows. In this example, the schema processor expanded the
complex types named documentX and documentY inline within the new IS document type:
Complex types expanded inline
If you select the option to generate complex types as separate document types, the
schema processor generates the document types as follows. In this example, the schema
processor generated three IS document types—one for the complex type named
documentY, one for the complex type named documentX (with a reference to documentY),
and one for the root element eltA (with references to documentX and documentY):
Complex types generated as separate document types
The schema processor generates all three document types in the same folder.
Note: If the complex type is anonymous, the schema processor expands it inline rather
than generate a separate document type.
If the XML schema you are using to generate an IS document type contains recursive
complex types (that is, element declarations that refer to their parent complex types
directly or indirectly), you can avoid errors in the document type generation process by
selecting the option to generate complex types as separate document types. (Selecting the
option to expand complex types inline will result in infinitely expanding nested
documents.)
Generating Fields for Substitution Groups

Integration Server processes substitution group elements in one of two ways, depending
on the value of the watt.core.schema.generateSubstitutionGroups property:
 When this property is set to true, the schema processor imports all substitution group
members (head element and substitutable elements) as optional fields, even though
they are defined as required elements in the XML schema definition.
 When this property is set to false, the resulting document type contains a field that
corresponds to the head element in the substitution group, but does not contain any
elements for members of the substitution group. This is the default.
If the head element is declared as abstract, the Integration Server does not include that
element in the IS document type.
To create an IS document type from an XML document, DTD, or XML schema

document type.
letters, numbers, and/or the underscore character. For information about reserved
words or characters, see “About Element Names” on page 47.
c Click Next.
4 Under Select a source, select one of the following:
Select... To...
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.
XML Schema Create an IS document type that matches the structure and fields in
an XML schema definition.
5 Click Next.
6 In the Enter the URL or select a local file field, 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.
7 Under Schema domain, specify the schema domain to which any IS schemas generated
will belong. Do one of the following:
 To add the IS schema to the default schema domain, select Use default schema
domain.
 To add the IS schemas to a specified schema domain, select Use specified schema
domain and provide the name of the schema domain in the text box. A schema
domain name must be a string that is a valid name of an element in Integration
Server. For more information about naming restrictions for Integration Server
elements, see “Guidelines for Naming Elements” on page 48.
For more information about schema domains, see “About Schema Domains” on
page 251.
8 Do one of the following based on your selection in step 4:
 If you selected XML, click Finish. Developer generates the IS document type using
the XML document you specified and displays it in the editor.
 If you selected DTD, 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.
 If you selected XML Schema, click Next and do the following:

1 Select the elements that you want to use as the root elements for the IS
document type. The IS document type will contain all of the selected root
elements.
To select multiple elements, press the CTRL key while selecting elements.
2 Under Complex type processing, select Expand complex types inline if you want
complex types to be expanded within the IS document type. That is, the
complex type will be a document variable within the IS document type.
Select Generate complex types as document types if you want separate IS
document types created for the complex types in the XML schema definition.
The resulting IS document type contains document references in place of a
document variable for the complex type.
3 Select the Generate all element references as document type references check box if
you want Integration Server to replace all references to global elements with
document references even if the element is referenced only once. Integration
Server generates an IS document type for each referenced element.
Leave the check box cleared if you want Integration Server to replace an
element reference with a document reference only if the element is referenced
more than once. When an element is referenced only once, Developer replaces
the element reference with a document field.
4 Select the appropriate option to specify whether Developer should process
complex types by expanding them inline in the editor or by generating them
as separate IS document types. Click Next.
5 If you want the IS document type to use different prefixes than those specified
in the XML schema definition, select the prefix you want to change and enter a
new prefix. Repeat for each namespace prefix that you want to change.
The prefix you assign must be unique and must be a valid XML NCName
6 Click Finish. Developer generates the IS document type(s) and displays them
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.
Developer might create multiple document types depending on the contents of the
source file and the processing options you selected.
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 488.
Creating an IS Document Type from a Broker Document Type

Important! The ability to create a publishable document type from a Broker document
type is deprecated.
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
document type.
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 document type.
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

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
Integration Server.
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”.
Assigning Universal Names to an IS Document Type

Every service and document type 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 and document
type on a webMethods Integration Server. For information about assigning a universal
name to service, see “Assigning Universal Names to Services and Document Types” on
page 157.
Editing an IS Document Type

When you make a change to an IS document type, keep the following information in
mind:
 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.
 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”
 The contents of an IS document type with a Model type property value other than
“Unordered” cannot be modified. However, the properties of the IS document type
can be modified.
 If Designer was used to create an IS document type from a source file such as an XML
schema definition or a WSDL document, Integration Server links the asset to it’s
source and prevents any editing of the document type contents in Developer or
Designer. Even if the Model type property is set to “Unordered” the document type
contents cannot be edited. If you want to edit this document type in Developer, you
first need to use Designer to break the as so cation between the document type and it’s
source file. Specifically, in Designer, set the Linked to source property to false. Then, if
the Model type is “Unordered”, you can use Developer to edit the document type
contents.
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.
If the service uses an IS document type from a different package, you must set up a
package dependency. For more information about package dependencies, see
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 279.)
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.
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
If you want the input… Select...
Entered in a large text area instead of a text field. Large Editor

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 Pick List
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.
Note: When executing a service, if you want a null value to be available as the first
option in the Pick List, set the dev.uicontrols.picklist.putNullStringAtTop
configuration parameter in the developer.cnf file located in the
Developer_directory\config directory to true. By default, this configuration parameter
is set to false and Developer adds the null value to the end of the Pick List.
Creating a Specification
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:
 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.)
 If the specification resides in a different package than the service, you must set up a
package dependency. For more information about package dependencies, see
 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.
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
Input/Output tab.
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 272. 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.
10 Performing Data Validation
 What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

 Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
 Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
 Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
 Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
 Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . 288
 Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
 Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
What Is 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
document type.
 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 256.
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 22, “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 282.
 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 282.
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 441.
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 441.
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
Input/Output tab.
 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 254.
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 255.
 The constraining facets you can specify depend on the content type. For more
information about the constraining facets for each content type, see Appendix 19,
“Supported Data Types” on page 439.
 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 254.
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 483.
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 23, “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 441.
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 279. For information about declaring
service input and output parameters, see “Declaring Input and Output Parameters for a
.
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 196.
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.
Input/Output tab with validation processing enabled
Service input values

will be validated every Service output
time the service values will not be
executes. validated.
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.
INVOKE properties with validation processing enabled
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.
Performing Document Validation

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.client.ldap:search 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 279.
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. For information about errors that can occur during validation, see
“Validation Errors and Exceptions” on page 291.
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 “Submitting and Receiving XML
Documents” on page 371. For more information about the pub.xml services, see the
webMethods Integration Server Built-In Services Reference.
Note: If an IS schema contains an element with a nillable attribute and the element
generated from the schema also contains the attribute xsi:nil="true", no document
validation is performed on the generated element.
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 <object>
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 <conformsTo> 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 <maxErrors> parameter to the number of allowed validation errors

validCursor.insertAfter( "maxErrors", "1000" );
validCursor.destroy();
// invoke pub.schema.validate to validate contents of <object>

IData validResult = context.invoke("pub.schema", "validate", validInput);
// check <isValid> to see whether <object> 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 23, “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.
11 Testing and Debugging Services
 Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

 Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
 Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
 Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
 Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
 Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
 Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
 Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
 Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
 Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
 Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Testing and Debugging

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, Integration Server provides tools for collecting run-time information that
can help debug a service. These include tools to:
 Debug services by saving the pipeline, examining the data, and then restoring the
pipeline at a later point in time.
 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 Broker/local triggers and publishable document
types, see the Publish-Subscribe Developer’s Guide.
Testing Services
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 browser-
based 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 38.
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 296.
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 298.
6 Click OK. Developer invokes the service with the specified set of input values.
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 299.
 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 301.
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 enter

simple Strings...
...and complex
documents and
document lists.
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 295 or “Testing Services from a Browser” on page 304.
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 295 or “Testing Services from a Browser” on page 304.
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.
 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 321. For information about modifying values in the
pipeline, see “Modifying the Current Pipeline” on page 319.
To load input values that have been saved to a file
page 295.
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
To examine the
contents of a
variable, select it in
the top pane...
...and view it in the

bottom pane.
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 321.
 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 321. For information about modifying an existing pipeline, see “Modifying
the Current Pipeline” on page 319.
 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 321. For information about
modifying an existing pipeline, see “Modifying the Current Pipeline” on page 319.
 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 The copied element's data definition.
Pipeline tab, the Input/Output tab, or a
document (IData object))
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
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.
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.)
Run-Time Exceptions
If a service that you run from Developer throws an exception, Developer reports the error
in a message box.
You can click the Details button to display the call stack and the pipeline at the point
where the error occurred.
Note: The Integration Server logs details about run-time exceptions, including the call
stack, the stack trace, and the cause of the error, in the Integration Server error log. This
information is useful for debugging services in a production environment. You can
control the level of detail written to the log by setting the
watt.server.deprecatedExceptionLogging parameter. For more information about this
parameter and the Integration Server error log, see webMethods Administering Integration
Server.
The Details button shows the call stack and the pipeline
...to display 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 72.
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
This service
threw the
exception.
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
This service
threw the
exception.
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 296.
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 298.
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 299.
 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 301.
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 308.
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 308.
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 309.
Step Executes the next flow step and then halts. For information about
using this command, see “Using the Step Tools” on page 310.
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 Through a Child Flow” on page 311 and
“Using the Step Tools with a MAP Step” on page 312.
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
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

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.
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 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 Trace
(breakpoints are ignored in this mode)
Trace to a specified point in the service without tracing child Trace to Here
services (breakpoints are ignored in this mode)
Trace to the end of the service or the next breakpoint, including the Trace Into
paths of all child services that this service invokes
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 125.
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 313.
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
of the following:
 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 Step Into
within it
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 125.
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 Through 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 311 or “To trace to a specified
point” on page 309 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.
To step into and out of 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 311 or “To
trace to a specified point” on page 309 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:
 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.
Setting Breakpoints
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 146.
 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.
To display the list of current 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.
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.
Disabling Flow Steps, Transformers, and Conditions

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
Disabled steps appear

dimmed in the editor.
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
Developer.
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.
Disabled transformers are not executed at run time
Transformers that are

disabled appear dimmed
on the Pipeline tab.
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 three 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.
 Automatically save the pipeline at run time using the Pipeline Debug property.
 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.
 Automatically load the pipeline at run time using the Pipeline Debug property.
 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
Developer.
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.
Note: When using MTOM streaming for SOAP attachments, messageContext variables
and/or XOPObject fields will not be available in the saved pipeline. A messageContext
variable is used by many pub.soap services to hold the SOAP message on which the
service acts. XOPObject fields are Objects that use the com.wm.util.XOPObject Java
wrapper type. For more information about MTOM Streaming, see the Web Services
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. Save Pipeline Locally
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 Save Pipeline to Server
Integration Server.
Select this command if you want to use the file to
dynamically restore the pipeline at run time using the
pub.flow:restorePipelineFromFile service.
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 Specify the name of the file in which you want the pipeline
Server saved. By default, Developer saves the file to
IntegrationServer_directory\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.
Automatically Saving the Pipeline at Run Time

You can automatically save the pipeline for a flow service at run time by using the Pipeline
Debug property. The Pipeline Debug property is located in the Runtime category of the
Properties panel. When the property is set to Save, the server saves the entire contents of
the pipeline to a file when the flow service is executed.
For more information about using the Pipeline Debug property to save the pipeline, see
“Using the Pipeline Debug Property” on page 153.
Manually 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.
To manually save the pipeline at run time
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 IntegrationServer_directory\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
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 restore options from the Pipeline Debug property.
 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 three ways to restore the contents of the pipeline:

 You can manually load the saved pipeline into the Results panel in Developer.
 You can automatically load the saved pipeline at run time by using the Pipeline Debug
property.
 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.
Note: When using MTOM streaming for SOAP attachments, messageContext variables
and/or XOPObject fields will not be available in the saved pipeline. A messageContext
variable is used by many pub.soap services to hold the SOAP message on which the
service acts. XOPObject fields are Objects that use the com.wm.util.XOPObject Java
wrapper type. For more information about MTOM Streaming, see the Web Services
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 “Manually Loading a Saved Pipeline at Run
Time” on page 325.
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 Restore pipeline from Server
on webMethods Integration 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 Specify the name of the file that you want to load.
Developer retrieves the file from
IntegrationServer_directory\pipeline.
Automatically Loading a Saved Pipeline at Run Time

You can automatically restore the pipeline for a flow service at run time by using the
Pipeline Debug property. The Pipeline Debug property is located in the Runtime category of
the Properties panel. To restore the pipeline using this property, you can choose to either
override or merge the existing pipeline with the contents from a previously saved file.
When a restore option is selected and the service is executed, the server loads the pipeline
file, folderName.serviceName.xml, from the IntegrationServer_directory\pipeline directory.
For more information about using the Pipeline Debug property to restore the pipeline,
see “Using the Pipeline Debug Property” on page 153.
Manually 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:
Key Description
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
IntegrationServer_directory\pipeline. For example, if you set
filename to “badPipeline.xml”, restorePipelineFromFile expects to
find that file in
IntegrationServer_directory\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.
service, reregister it on webMethods Integration Server, and reload its package.)
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:
IntegrationServer_directory\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 328.
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 or a specific facility within the Integration Server is
operating.
You can specify the server debug level when you start the server. The debug level can
range from Off, where nothing is logged, to Trace, in which the server keeps an extremely
detailed log. For more information about the available logging levels, see the webMethods
Audit Logging Guide.
The following example shows the startup command you would use to start the server at
the trace debug level.
bin\server.bat –debug trace (under Windows)
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. The default value of
watt.debug.level is Info.
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.
Instead of running the entire Integration Server at a higher debug level, you can increase
the logging level for a specific facility in Integration Server. For example, you might set
the logging level for the Services facility to Trace. For more information about
configuring server logging, see webMethods Audit Logging Guide.
Important! Debug levels above Info produce lots of detail and can quickly generate an
extremely large log file. You should not run your server at the Debug or Trace levels
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 webMethods
Writing Information to the Server Log

webMethods Integration Server 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.0004C] begin database update
2002-05-28 16:57:56 EDT [ISP.0090.0004C] 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.
Key Description
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.
Key Description
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 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.
If you do not specify level, the Fatal level 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 327.
For additional information about pub.flow:debugLog, see the webMethods Integration Server
Built-In Services Reference.
Dumping the Pipeline to the Log

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\IntegrationServer_directory\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 Rope
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.
Key Description
level Optional. A String 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, Fatal is assumed, which means that the
pipeline 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 327.
4 Execute the service. For additional information about pub.flow:tracePipeline, see the
12 Building Coded Services
 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

 Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
 How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
 Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
 Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
 Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
 Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
 Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Basic Concepts
In addition to using the built-in services that webMethods Integration Server 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
Developer_directory\doc\api\Java\index.html.
Creating IData Objects

You use the IDataFactory class to create IData objects. For example:
static IData myIDataObject;
static
{
myIDataObject = 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.
You can use Developer’s IDE for creating small, simple services. However Designer is a
much better IDE for creating Java services whether small or large. For more information
about creating Java services using Designer, see the webMethods Designer Online Help.
Alternatively, you can use your own Java IDE. 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 341.
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 or Designer, your service is automatically
combined 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 or Designer, 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
Developer.
Stage 1 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 339.
Stage 2 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 338.
Stage 3 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 78.
 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 47.
 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 105.
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.
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
Developer
automatically
generates required
code for you.
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.
You use the Java service editor to write the body of your service
Type your
code in here.
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.
5 Click Finish.
6 If you know the set of inputs and outputs your program uses, specify these using the
Input/Output tab.
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 339.
7 Type the code for your service at the top of the Java service editor. For information
about Java classes provided with webMethods Integration Server, see the webMethods
Integration Server Java API Reference in Developer_directory\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 141.
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 145 and “Assigning an Output
Template to a Service” on page 142.
Building Java Services with Your Own IDE

There might be times when you want to use your own IDE instead of Developer or
Designer 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:
IntegrationServer_directory\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.
IntegrationServer_directory\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 21, “jcode
tags” would have the following path:
IntegrationServer_directory\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 Integration Server provides classes that you can use with Java services that
you build. See the webMethods Integration Server Java API Reference in:
Developer_directory\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 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 338).
Stage 2 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 339).
Stage 3 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 343.
Stage 4 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 344.
Stage 5 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 345.
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
 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.
.
.
.
// --- <<IS-START-IMPORTS>> ---
import com.wm.data.*;
import java.util.*;
// --- <<IS-END-IMPORTS>> ---
.
.
.
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 21, “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 want the jcode utility to run using a different compiler, specify the compiler you
want to use in the jcode.bat file. Set the watt.server.compile system property on the line
with the Java command. The property must have the following format:
"-Dwatt.server.compile="path_to_your_java_compile -classpath {0} -d {1} {2}"
For example:
-Dwatt.server.compile="C:\java\jdk1.6.0_11\bin\javac -classpath {0} -d {1}
{2}"
Using this example, the Java command would be changed to the following:
"%JAVA_DIR%\bin\java" -Dwatt.server.compile="C:\java\jdk1.6.0_11\bin\javac -
classpath {0} -d {1} {2}" -classpath
"%IS_DIR%\..\common\lib\ext\mail.jar;%IS_DIR%\..\common\lib\ext\enttoolkit.j
ar;%IS_DIR%\..\common\lib\wm-
g11nutils.jar;%IS_DIR%\..\common\lib\ext\icu4j.jar;%IS_DIR%\..\common\lib\wm
-isclient.jar;%IS_DIR%\lib\wm-isserver.jar" com.wm.app.b2b.server.NodeUtil
"%IS_DIR%" %1 %2 %3 %4 %5
The watt.server.compile property specifies the compiler command that you want
Integration Server to use to compile Java services. For more information about this
property, see the webMethods Administering Integration Server.
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/C++ compiler installed on the host where webMethods
Integration Server in installed.
 Make sure that you have completed the procedures specified in
IntegrationServer_directory/sdk/c/README and/or
IntegrationServer_directory/sdk/cpp/doc/README to build the platform support
libraries needed by Integration Server and Developer.
 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 78. (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 47.
 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:
 Set the Windows system environment variable PATH to include
IntegrationServer_directory\lib
-OR-
 Copy the wmJNI.dll and wmJNIc.dll files located in
IntegrationServer_directory\lib to the IntegrationServer_directory directory
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.
To generate C/C++ project files

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.
7 Click Finish.
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:
IntegrationServer_directory\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 Developer_directory\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.
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 348.
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 352.
 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 The program ID of the object that you want to invoke.
–OR–
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:
Name Description
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.
13 Creating Client Code
 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

 Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
 Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
 Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
 Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
 Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
 Building a REST Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Basic Concepts
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
 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.
By default, Integration Server writes a response message to an HTTP client using the
same content type that was included in the request message. However, you can specify
that your service send the response message using a different format. For example, if
your service receives a request that specifies text/xml as the content type, you can send a
response message that specifies text/html for the content type. To change the content-type
of the response message, code your service to call the pub.flow:setResponseHeader service
before it writes output to the pipeline.
Building a Java Client

You can use Developer to generate Java client code that invokes a service.
Your classpath must consist of at least the following:
Software AG_directory\common\lib\wm-isclient.jar
Software AG_directory\common\lib\ext\mail.jar
Software AG_directory\common\lib\ext\enttoolkit.jar
Limitations
 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.
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.
6 Click Finish.
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
 webMethods Integration Server is running.
 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 wm-isclient.jar file is in the classpath for Developer. The client.jar file is a
webMethods file that is located in the Software AG_directory\common\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.
6 Click Finish.
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 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
Developer_directory\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 Type Library is installed.
Note: The webMethods Type Library is a COM object that Visual Basic uses to interact
with webMethods Integration Server. The webMethods Type Library is automatically
installed when you install Developer.
Environment Setup
Your system PATH environment variable must include the following directory:
Software AG_directory\jvm\win150\jre\bin\client
-OR-
Software AG_directory\jvm\win160\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.
6 Click Finish.
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
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
Files Containing the Code that Invokes the Service
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 Developer 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 Type Library is installed.
Note: The webMethods Type Library is a COM object that Visual Basic uses to interact
with webMethods Integration Server. The webMethods 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.
6 Click Finish.
Developer generates several files, including the serviceNameReadMe.txt file. This file
contains detailed information about all generated files.
7 Copy the wmXLTemplate.xls file that Developer provides to the directory that
contains the client code that Developer generated. The wmXLTemplate.xls file is
located in the Developer_directory\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 Developer 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 webMethods Administering Integration Server.
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:
1 2 3 4 5
http://IS_server:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1
Item Description
1 Identifies the webMethods Integration Server on which the service you want
to invoke resides.
2 Specifies the required keyword “invoke”, which tells webMethods
Integration Server that the URL identifies a service that is to be invoked.
3 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.
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.
Using the HTTP GET Method

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 367.
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:
<SELECT NAME="sku">
<OPTION VALUE="A1">A1</OPTION>
<OPTION VALUE="B2">B2</OPTION>
<OPTION VALUE="C3">C3</OPTION>
</SELECT>
<INPUT TYPE="TEXT" NAME="quantity" VALUE="1">
Specify the URL for the service in the ACTION attribute and “POST” in the METHOD attribute.
For example:
<FORM ACTION="/invoke/sample.webPageDemo/getProductCost" METHOD="POST">
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 367.
Input to the Service

Regardless of whether 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, the
following URL specifies input values that contain the variable sku with value A1 and
quantity with value 1, and the resulting IData object that Integration Server creates:
/invoke/sample.webPageDemo/order?sku=A1&quantity=1
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 Integration Server receives multiple input values that are associated with the same
variable name, the String variable in the IData object will contain only the value of the
first variable. The String list variable will contain all the values. For example, the
following shows a URL that contains two values for the variable year and the resulting
IData object that Integration Server creates:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999
Key Value Data Type

year 1998 String
yearList 1998 String list
1999
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:
<INPUT TYPE="checkbox" NAME="Color" VALUE="blue">Blue<BR>
<INPUT TYPE="checkbox" NAME="Color" VALUE="green">Green<BR>
<INPUT TYPE="checkbox" NAME="Color" VALUE="red">Red<BR>
If the browser user selects all check boxes, the document that is posted to Integration
Server will contain three values for the variable named Color. The following shows the
IData object that the server passes to the service:
Key Value Data Type

Color blue String
ColorList blue String list
green
red
Controlling How Integration Server Handles Duplicate Tokens in Input

You can control how Integration Server handles duplicate tokens, that is, multiple
occurrences of a variable name in a request, by using the watt.server.http.listRequestVars
parameter.
With the default setting, asNeeded, Integration Server creates an IData object that contains
a String variable that contains the first occurrence of the variable and a String list variable
that contains all occurrences of the variable. For example, this request:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999&month=June
Integration Server creates the following IData object:
Key Value Data Type

year 1998 String
1999
month June String
To instruct Integration Server to create a List of all input variables, set the parameter to
always. For example, for this request:
Key Value Data Type

year 1998 String
1999
month June String
monthList June String list
To instruct Integration Server to ignore duplicates of the same variable, set this parameter
to never. For example, for this request:
Key Value Data Type

year 1998 String
month June String
To instruct Integration Server to throw a ServiceException if duplicates of the same

variable are found, set this parameter to error.
For more information about the watt.server.http.listRequestVars, see webMethods
Output from the Service

By default, webMethods Integration Server displays the output from a service in an
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 142.
Building a REST Client

To interact with a REST application, a customer or partner must create a REST client that
can send properly formed requests to the REST server and handle responses sent by the
server. For more information about what a REST client needs to do, refer to REST Services
14 Submitting and Receiving XML Documents
 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
 Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
 Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
 Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
 Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
 Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Overview
You can submit XML documents to the webMethods Integration Server from a client,
and have the Integration Server receive XML documents with services that you write. The
Integration Server provides the following automated mechanisms for receiving arbitrary
XML documents, parsing them or directly passing them as input to a specified service.
 A client submits an XML document to a service in a String variable (of any name),
which the target service converts into a node using pub.xml:xmlStringToXMLNode.
 A client submits an XML document to a service in a special String variable named
$xmldata, and webMethods Integration Server automatically parses the variable and
passes it to the service as a node.
 A client posts an XML document to a service via HTTP, and Integration Server parses
the XML and passes it to the service as a node or directly passes it to the service as a
stream or byte without parsing.
 A client FTPs an XML document to a service.
 A client e-mails an XML document to a service.
 A client sends the XML document as an e-mail attachment.
Submitting and Receiving XML in a String Variable

One way to submit an XML document to the webMethods Integration Server is to pass
the entire XML document to a service in a String variable. When you use this approach,
you should code the target service to execute pub.xml:xmlStringToXMLNode to convert the
String variable (that is, the XML document) to a node. Once the XML document is
represented as a node, it exists in a form that can be queried or converted to an IData
object. For information about using xmlStringToXMLNode, see the webMethods Integration
Example: Submitting XML in a String

The following code fragment shows how a Java client might submit an XML document to
a service called purch:postOrder on webMethods Integration Server. In this example, the
client:
1 Loads the XML document into a String
2 Puts the String into the element orders in an IData object named inputs
3 Invokes purch:postOrder on the server at localhost:5555
import com.wm.app.b2b.client.*;
import com.wm.util.*;
import java.io.*;
public class ArbitraryXMLClient
.
.
.
//--Load XML into orders string
1 String orders = YourLoadXMLMethod(orderFile);
//--Put input values into IData object
IData inputs = IDataFactory.create();
IDataCursor inputsCursor = inputs.getCursor();
2 inputsCursor.insertAfter("orders", orders);
inputsCursor.insertAfter("authCode", authCode);
//--Submit request to server
c.connect("localhost:5555", "null", null);
3 IData outputs = c.invoke("purch", "postOrder",
inputs);
c.disconnect();
.
.
.
Example: Receiving XML in a String

On the server, the receiving service should be coded to pass the XML in the String
variable to pub.xml:xmlStringToXMLNode. This produces a node that can be subsequently
queried or converted to an IData object.
In the previous example, purch:postOrder should be coded to pass the XML document in
orders to pub.xml:xmlStringToXMLNode. For information about the services that you can use to
manipulate nodes, see pub.xml:queryXMLNode and pub.xml:xmlNodeToDocument in the
Submitting and Receiving XML in $xmldata

Submitting an XML document to webMethods Integration Server using $xmldata is
similar to submitting it as a String variable, but in this case, the service receiving the XML
document does not need to include a parsing step; webMethods Integration Server
automatically parses the contents of $xmldata. However, you can bypass automatic parsing
and send the body of the request directly to the service by including the xmlFormat input
value in the URL. For more information, see “Submitting and Receiving XML via
$xmldata without Parsing” on page 375.
The name $xmldata has special meaning to the Integration Server in that it assumes the
value of this variable is an XML document. When it receives a request that includes an
input variable named $xmldata, the server automatically parses the contents of that
variable, producing an XML node that can be used by any service that takes a node as
input.
Example: Submitting and Receiving XML in $xmldata

The following example shows a client application that reads an XML document from a
file, assigns the text in the file to $xmldata and then passes $xmldata to a service called
sales:getOrder.
import com.wm.app.b2b.client.*;
import com.wm.util.*;
import java.io.*;
public class ArbitraryXMLClient
{
public static void main(String args[])
throws Exception
{
//--Read XML document from a specified file (or from stdin)
Context c = new Context();
IData inputs = IDataFactory.create();
IDataCursor inputsCursor = inputs.getCursor();
Reader in = null;
if(args.length > 0)
{
in = new InputStreamReader(new
FileInputStream(args[0]));
}
else
{
in = new InputStreamReader(System.in);
}
char[] buf = new char[8192];
int count = 0;
StringBuffer sb = new StringBuffer();
while((count = in.read(buf)) != -1)
{
sb.append(buf, 0, count);
}
//--Assign XML document to string variable
String xmldata = sb.toString();
//--Put XML document into $xmldata in IData object
inputsCursor.insertAfter("$xmldata", xmldata);
//--Submit request to server
c.connect("localhost:5555", "null", null);
IData outputs = c.invoke("sales", "getOrder", inputs);
c.disconnect();
//--Display the returned output values
System.out.println(outputs);
}
The service invoked by this client must be a service that takes a node as an input variable
(for example, queryXMLNode, xmlNodeToDocument), because this is what webMethods
Integration Server produces when it receives this request.
Important! This example shows a Java-based client; however, any type of IS client (even
a browser-based client) can be used. With a browser-based client, you would post the
XML document as the value portion of a $xmldata=value pair. You may post other
name=value pairs with the request.
Submitting and Receiving XML via $xmldata without Parsing

When a client posts an XML document to a service via $xlmldata, webMethods
Integration Server automatically parses the XML and passes it to the service as a node. In
some cases, parsing can slowdown the execution of a service. For example, an
applications might handle the XML as a simple string. In this case, the automatic parsing
is unnecessary and should be avoided.
You can bypass parsing of XML documents and specify the XML format for submitting
and receiving XML, by adding xmlFormat to the service URL.
Note: You can change the default parsing behavior for Integration Server using the
watt.server.http.xmlFormat parameter. For more information, see the webMethods
Administering Integration Server. The xmlFormat input value overrides the
watt.server.http.xmlFormat parameter.
Example: Submitting and Receiving XML via $xmldata without

Parsing
The following example describes the input parameter xmlFormat. You can set this
parameter if you use pub.client:http to POST an XML document to a service and you do not
want Integration Server to parse the XML as a node.
If this parameter is not set or is invalid, the default behavior defined by the
watt.server.http.xmlFormat property is used.
Set this variable To ...
url The URL of the service that you want to invoke. The following value
would invoke the purch:postOrder service from a server named
“rubicon” with port number “5555.”
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=stream
xmlFormat=stream directs the Integration Server to pass XML as a

stream directly to the requested service without parsing.
When this parameter is set to stream, the XML appears in the input
pipeline of the service as an InputStream named xmlStream.
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=bytes
xmlFormat=bytes directs Integration Server to pass XML as bytes

directly to the requested service without parsing. When this
parameter is set to bytes, the XML appears in the input pipeline of
the service as a byte array named xmlBytes.
Note: Set xmlFormat to node or omit it if you want Integration Server

to automatically parse the XML and pass it to the service as a node.
method get
headers.Content text/xml
-Type
data.args Name Value
$xmldata The XML document that you want to post.
Submitting and Receiving XML via HTTP

A client can post an XML document to a service that receives it via HTTP. To use this
approach, you must have a client that can:
 Send a string of data (an XML document) to webMethods Integration Server using the
HTTP POST or HTTP PUT methods.
–AND–
 Set the value of the Content-Type request-header field to text/xml.
When webMethods Integration Server receives an HTTP POST request where Content-
Type is text/xml, it automatically parses the body of the request (the XML document) and
passes it as a node to the service specified in the request’s URL. However, you can bypass
automatic parsing and send the body of the request directly to the service by including
the xmlFormat input value in the URL. For more information, see “Submitting and
Receiving XML via HTTP without Parsing” on page 378.
Client Requirements
Since most browsers do not allow you to modify the Content-Type header field, they are
not suitable clients for this type of submission. Clients that you might use to submit an
XML document in this manner are PERL scripts (which allows you to build and issue
HTTP requests) or the webMethods Integration Server service, pub.client:http.
Regardless of which client you use, it must do the following:
 Submit a POST request to webMethods Integration Server.
 Address the request to the URL of a service (for example,
http://rubicon:5555/invoke/purch/postOrder ).
 Set the Content-Type header field to text/xml.

 Contain an XML document in the body of the message. The document must be the
only text that appears in the body of the request. Do not assign it to a name=value
pair.
Important! When you submit the XML document, place an extra carriage return/new
line (\r\n) at the end of it to indicate the end of the XML document.
Example: Submitting and Receiving XML via HTTP

The following example describes the values that you set if you use pub.client:http to POST
an XML document to a service.
Set this variable... To...
url The URL of the service that you want to invoke. The following
value would invoke the purch:postOrder service from a server
named “rubicon” with port number “5555.”
Example http://rubicon:5555/invoke/purch/postOrder
method post
headers.Content-Type text/xml
data.string The XML document that you want to post.

–OR–
data.bytes
You will also set any optional HTTP parameters, such as authorization information, that
are required by your application.
Submitting and Receiving XML via HTTP without Parsing

When a client posts an XML document to a service via HTTP, Integration Server
automatically parses the XML and passes it to the service as a node. In some cases,
parsing can slow down the execution of a service.
For example, an applications might handle the XML as a simple string. In this case, the
automatic parsing is unnecessary and should be avoided.
You can bypass parsing of XML documents and specify the XML format for submitting
and receiving XML, by adding xmlFormat to the service URL.
Note: You can change the default parsing behavior for Integration Server using the
watt.server.http.xmlFormat parameter. For more information, see the webMethods
Administering Integration Server. The xmlFormat input value overrides the
watt.server.http.xmlFormat parameter.
Example: Submitting and Receiving XML via HTTP without Parsing

The following example describes the input parameter xmlFormat. You can set this
parameter if you use pub.client:http to POST an XML document to a service and you do
not want Integration Server to parse the XML as a node. If this parameter is not set or is
invalid, the default behavior defined by the watt.server.http.xmlFormat property is used.
To
url The URL of the service that you want to invoke. The following
value would invoke the purch:postOrder service from a server
named “rubicon” with port number “5555.”
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=stre
am
xmlFormat=stream directs the Integration Server to pass XML as

a stream directly to the requested service without parsing.
When this parameter is set to stream, the XML appears in the
input pipeline of the service as an InputStream named
xmlStream.
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=byte
s
xmlFormat=bytes directs Integration Server to pass XML as

bytes directly to the requested service without parsing.
When this parameter is set to bytes, the XML appears in the
input pipeline of the service as a byte array named xmlBytes.
method post
headers.Content-Type text/xml
data.string The XML document that you want to post.
–OR–
data.bytes
Submitting and Receiving XML via FTP

You can FTP an XML document to webMethods Integration Server’s FTP listening port.
(By default the FTP port is assigned to port 8021. However, this assignment is
configurable, so you should check with your webMethods Integration Server
administrator to see which port is used for FTP communications on your webMethods
Integration Server.)
When a client puts a file on the Integration Server for the purpose of invoking a service,
the FTP Listener will choose a content handler, based on the file extension, to convert the
file content into the input values for the service to invoke. The Integration Server’s
lib/mime.types file contains the mapping of file extension to content type.
Tip! You can edit the mappings in the lib/mime.types file (and reload it without
restarting Integration Server), by selecting Settings > Resources > Mime Types from the
Integration Server Administrator screen.
When the Integration Server receives an XML document on the FTP listening port, it
automatically parses the document and passes it as a node to the service in the directory
where the file was FTPed.
To submit an XML document to webMethods Integration Server via FTP:
 The XML document can be contained in a file that has either:
 A file extension of “xml”
 A file extension whose mime type is registered with the server as text/xml.
To do this, edit the Integration Server’s lib/mime.types file. For example:
text/xml mimetype
 No file extension
To configure a content handler to handle files that have no extension, use the
special key ftp_no_extension in the lib/mime.types file to indicate a null
extension. Then, specify the content type mapped to a null extension. For
example, the following XML content handler is used to handle files without an
extension:
text/xml ftp_no_extension
If you want to use a different key to specify a null extension, use the property
watt.net.ftp.noExtensionKey to specify the key used in lib/mime.types to
specify a file with no extension. The default value of this property is
ftp_no_extension.
 The service to which you want to pass the document must take a node as input.
Client Requirements
If you want to submit an XML document to a service through FTP, the application
sending the document must do the following:
1 Initiate an FTP session on webMethods Integration Server’s FTP listening port.
2 Point to the directory that contains the service to which you want to pass the XML
document.
Example cd \ns\Purchasing\SubmitOrder
Important! Note that the root directory for this operation is your webMethods
Integration Server’s namespace directory (ns), not the root directory of the target
machine. Therefore, if you want to FTP a file to a service in the Purchasing package,
you use \ns\Purchasing\ServiceName as the path to that service, not
IntegrationServer_directory\ns\Purchasing\ServiceName.
3 Copy the XML document to this directory using the following command:
put XMLDoc.xml
or
put XMLDoc
Where XMLDoc is the name of the file that you want to pass to webMethods
Integration Server. The file extension can be something other than “xml” if the
extension’s mime type is registered with the server as text/xml. Alternatively, the file
extension can be omitted if you specify the special key ftp_no_extension in the
lib/mime.types file to indicate a null extension. See “Submitting and Receiving XML
via FTP” on page 379 for details.
Example put PurchaseOrder.xml
Note that the XML document you FTP to webMethods Integration Server is never
actually written to the server’s file system. The XML document you send and the
output file it produces (see below), are written to a virtual directory system
maintained in your IS session.
FTPing a File from a webMethods Integration Server

The pub.client folder contains built-in services you can use to FTP a file from a
webMethods Integration Server. For information about these services, see the webMethods
Receiving XML via FTP

The results from a service executed by an FTP request are written to the same virtual
directory where the XML document was initially FTPed.
 If the service does not have an output template assigned to it, the results (that is, the
contents of the pipeline) are XML-encoded and returned as an XML document.
 If the service has an XML output template assigned to it, that template is applied to
the results. (If the template is not an XML-based template, it is not applied.)
The name of the output file to which results are written is:
XMLDoc.xml.out
Where XMLDoc.xml is the name of the XML file initially FTPed to the service. (The file
extension can be something other than “xml” if the extension’s mime type is registered
with the server as text/xml.)
You retrieve this XML document using the FTP “get” command. For example, if you put
an XML document called PurchaseOrder.xml on webMethods Integration Server, you would
use the following FTP command to get its results:
Example get PurchaseOrder.xml.out
Important! We recommend that you use a unique name for each XML document that
you FTP to webMethods Integration Server (perhaps by attaching a timestamp to the
name) so that you do not inadvertently overwrite other FTPed XML documents or
their results during an FTP session.
When you end the FTP session, webMethods Integration Server automatically deletes the
original file and its results from your session.
Submitting and Receiving XML via E-mail

You can e-mail an XML document to an e-mail mailbox and have webMethods
Integration Server automatically retrieve the e-mail message and process the XML
document it contains. To do this, your webMethods Integration Server must be
configured with an e-mail port that monitors the mailbox to which the XML document
will be sent. (Consult your webMethods Integration Server administrator to see whether
an e-mail port has been set up on your webMethods Integration Server.)
When an XML document arrives in the e-mail port’s mailbox, webMethods Integration
Server automatically retrieves the message, parses the attached XML document, and
passes the XML document as a node to the service specified on the e-mail’s subject line
(or, if a service is not specified on the subject line, the e-mail port’s default service).
Client Requirements
To submit an XML document to webMethods Integration Server via e-mail, your client
program must:
 Put the XML document in an e-mail attachment.
 Set the e-mail’s Content-Type header to text/xml.
 Specify the name of the service that will process the XML document in the e-mail’s
subject line. If you leave the subject line empty, the XML document will be processed
by the global service if one is defined or, if not, by the default service assigned to the
e-mail port (if one has been assigned). For information about specifying the port’s
default service, see webMethods Administering Integration Server.
The service that processes the XML document must take a node as input.
Example: Sending XML via E-mail

The following example describes the values that you would set if you used pub.client:smtp
to e-mail an XML document to a service. (For more information about using this service,
see the webMethods Integration Server Built-In Services Reference.)
to A String specifying the e-mail address that webMethods

Integration Server’s e-mail port monitors.
subject A String specifying the fully qualified name of the service
that webMethods Integration Server passes the attached
XML document to.
Example: orders:ProcessPO
If you do not specify subject, the e-mail port will invoke its
default service (if one has been assigned to it).
from A String containing the e-mail address to which the results

of the service are sent.
body A String containing input parameters for the service in URL
query string format. The following example sets five
parameters: one, two, and three are set to the values 1, 2 and 3,
respectively. The parameters $user and $pass have special
meaning to the e-mail port. You use these parameters to
specify the user name and password for the e-mail port. You
must specify these two parameters if authentication is
enabled on the e-mail port.
Example:
one=1&two=2&three=3&$user=Administrator&$pass=manage
attachments.contenttype A String set to: text/xml

attachments.content The byte [] or a String containing the XML document.
–OR–
attachments.filename A String specifying the fully qualified name of the file
containing the XML document.
Receiving XML via E-mail

If your e-mail port is configured to return results, the results from a service invoked
through the port are e-mailed back to the sender of the original message, in an
attachment file called xml.out.
 If the service does not have an output template assigned to it, the results from the
service (that is, the contents of the pipeline) are XML-encoded and returned as an
XML document.
 If the service has an output template assigned to it, that template is applied to the
results.
Important! By default, the e-mail port does not return any results from requests that it
receives. If you want the port to return results, you must explicitly configure it to do
so. For information about configuring the e-mail port to return results, see
15 Subscribing to Events
 The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

 Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
 Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
 Invoking Event Handlers Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
 Working with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
The Event Manager

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:
Event Type Description

Alarm Occurs when 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 Occurs when a service generates audit data. Subscribe to audit
events to invoke specific actions when a particular service or class of
service executes.
Error Occurs when Integration Server generates an error. When
Integration Server writes an entry to the error.log, Integration Server
also creates an error event.
Exception Occurs 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 Occurs when a client uses guaranteed delivery to invoke a service
Delivery on an 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.
JMS Delivery Occurs when the contents of a JMS message sent from the client side
Failure queue cause the JMS provider to throw a non-transient error.
Subscribe to JMS delivery failure events to capture information
about JMS messages that the JMS provider did not process
successfully. For example, you might want to use the event handler
to send notification or log information about the undelivered JMS
message.

JMS Retrieval Occurs when a JMS trigger service ends because of a non-transient
Failure or transient error and Integration Server is configured to generate
JMS retrieval failure events. Subscribe to JMS retrieval failure events
to invoke event handlers when JMS message processing ends in
error.
Journal Occurs when Integration Server writes an entry to the journal log.
Port Status Occurs each time 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 Occurs 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.
Security Occurs when an administrative or operational security action takes
place on Integration Server and that security action is configured for
auditing.
Administrative actions refer to configuration changes related to
Integration Server security activities. Examples of security actions
include: modification to authorization, authentication, port settings,
audit settings, SSL configuration, password lengths, and root
certificates.
Operational actions refer to successful and unsuccessful login
attempts to Integration Server, successful or unsuccessful access to
Integration Server services, documents, and portlets, and changes to
messaging settings.
Session Occurs 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 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 Occur when an Integration Server begins and finishes processing a
events 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.
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.
 An event handler can be invoked synchronously or asynchronously. For more
information, see “Invoking Event Handlers Synchronously or Asynchronously” on
page 398.
 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

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

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.
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 391.
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: 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: IntegrationServer_directory\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
Error Event The error message text. The following filter specifies that any error
event with a message that contains the word "missing" will invoke
the event handler.
*missing*
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.
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*
JMS Delivery The name of the JMS connection alias used to send the message to
Failure Event the JMS provider.
The following filter specifies that a JMS delivery failure event
involving a JMS connection alias with “XA” in the JMS connection
alias name will invoke the event handler:
*XA*
JMS Retrieval The fully qualified name of the JMS trigger that called the trigger
Failure Event service for which the error occurred.
The following filter specifies that a JMS retrieval failure event
involving a JMS trigger named “ordering:processTransaction” will
invoke the event handler:
*ordering:processTransaction*
Journal Event The major code and minor code of the generated event. The
format of the filter is <majorCode>.<minorCode>. For example, the
following filter specifies that any journal event with major code of
28 followed by a minor code of 34 will invoke the event handler:
*28.34*
Port Status Event N/A

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.
The following filter specifies that a replication event involving the
package named “AcmePartnerPkg” will invoke the event handler:
AcmePartnerPkg
Security Event N/A

The filter for all session end events is the following:
*
Session End Event N/A
The filter for all session end events is the following:
*
Session Expire N/A

Event
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

The filter for all Tx Start events is the following:
*
Creating Event Filters for Services

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 subscriptions. Your changes take effect
immediately.
Building an Event Handler

Building an event handler involves the following basic stages:
Stage 1 Creating an empty service. During this stage, you create the empty service that
you want to use as an event handler.
Stage 2 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.
Stage 3 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.
Stage 4 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.
Stage 5 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,
[email protected]).
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…
Service Click and use the Select dialog box to navigate to and select the
processLogon service.
Filter 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.
Comment Specify a descriptive comment about this subscription.
Enabled Select true to activate the subscription.
5 Click OK. Subscriptions take effect immediately.
Invoking Event Handlers Synchronously or Asynchronously

By default, Integration Server invokes event handlers that subscribe to events
synchronously. Once the event handler is invoked, Integration Server waits for a reply
before executing the next step in the flow service. This configuration is useful for
environments that do not allow the use of thread or for processes that require immediate
responses.
You can configure Integration Server to process the event handlers asynchronously. In
this case, once the event handler is invoked, Integration Server executes the next step in
the flow service immediately. The server does not wait for a reply before continuing the
execution of the service. Each process runs as a separate thread, thereby increasing the
performance significantly.
There are server configuration parameters specific to each event type that you can use to
specify whether the event handlers (services) that subscribe to the events are to be
invoked synchronously or asynchronously. These server configuration parameters will be
in the format: watt.server.event.eventType.async.
Set the value of the server configuration parameter specific to the event to true, if you
want Integration Server to invoke the event handlers that subscribe to the event
asynchronously. Set the value of the server configuration parameter specific to the event
to false, if you want Integration Server to invoke the event handlers that subscribe to the
event synchronously. The default value is true.
For more information about specifying the server configuration parameters, refer to
Working with Events
Working with Alarm Events

An alarm event occurs when 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 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.
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 159.
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. 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).
Working with Guaranteed Delivery Events

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
webMethods Integration Server webMethods Integration Server

(local) (remote)
1 2
Service A Service B
5 4 3
Stage Description
1 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.
2 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.
3 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 The remote Integration Server sends the results of Service B to the requesting
client (here, the local Integration Server).
5 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 details about guaranteed delivery, see the Guaranteed Delivery Developer’s Guide.
Working with JMS Delivery Failure Events

Integration Server generates a JMS delivery failure event when a message written to the
client side queue cannot be delivered to the JMS provider. When a transient error occurs,
several delivery attempts may have been made.
You might want to create an event handler for a JMS delivery failure event to send
notification or log information about the undelivered JMS message. You can also create
an event handler that attempts to re-send the message to the JMS provider.
Working with JMS Retrieval Failure Events

By default, Integration Server generates JMS retrieval failure events when errors occur
during message retrieval and JMS trigger processing. You can build event handlers that
subscribe to and handle the JMS retrieval failure events.
A JMS retrieval failure event occurs in the following situations:
 A trigger service executed by a JMS trigger throws a non-transient error and the
watt.server.jms.trigger.raiseEventOnException property is set to true (the default).
 A trigger service associated with a JMS trigger ends because of a transient error, all
retry attempts have been made, and the JMS trigger is configured to throw an
exception on retry failure. In addition, the
watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the default).
 The maximum delivery count from the JMS provider has been met for the message
and the watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the
default).
The watt.server.jms.trigger.maxDeliveryCount property specifies the maximum
number of times the JMS provider can deliver a message to Integration Server. The
default is 100. In a JMS message, the property JMSXDeliveryCount specifies the
number of times the JMS provider delivered the message. Most JMS providers set this
value.
 While performing exactly-once processing, the connection to the document history
database is unavailable, and transient error handling for the JMS trigger is configured
to Throw exception (non-transacted JMS trigger) or Recover only (transacted JMS
trigger). In addition, the watt.server.jms.trigger.raiseEventOnRetryFailure property is
set to true (the default).
 While performing exactly-once processing, the document resolver service ends with
an ISRuntimeException, and transient error handling for the JMS trigger is
configured to Throw exception (non-transacted JMS trigger) or Recover only (transacted
JMS trigger). In addition, the watt.server.jms.trigger.raiseEventOnRetryFailure
property is set to true (the default).
 While performing exactly-once processing, the document resolver service ends with
an exception other than an ISRuntimeException. In addition, the
watt.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the default).
A service that functions as an event handler for a JMS retrieval failure event should use
the pub.event:jmsReceiveErrorEvent specification as its service signature. For more
information about the pub.event:jmsReceiveErrorEvent specification, see the webMethods
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 webMethods Administering
Integration Server.
Working with Replication Events

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.
 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
Working with Security Events

A security event occurs when an administrative or operational security action takes place
on Integration Server and that security action is configured for auditing.
Administrative actions refer to configuration changes related to Integration Server
security activities. Operational actions refer to successful and unsuccessful login attempts
and access to Integration Server services, documents, and portlets.
Administrative security events include:
 Creating, modifying, and deleting packages, folders, and services.
 Creating, deleting, or modifying authentication related information. This includes
creating new users, deleting users, changing their security attributes (for example,
passwords), setting or modifying the mapping between certificates and users, and so
on.
 Creating, deleting, or modifying authorization related information. This includes

creating, modifying, and deleting ACLs.
 Creating, deleting, or modifying port settings. This includes defining allowed or
denied actions on the port, port modes (allowed or denied by default in Integration
Server), and certificate handling.
 Configuring SSL settings in Integration Server.
 Modifying or resetting Outbound Passwords.
Operational security events include:
 Successful logins to the Integration Server.
 Unsuccessful login attempts to the Integration Server. The login attempt failure could
be because of incorrect password, disabled account, SSL failure, or expired certificate.
 Successful and unsuccessful accesses to services, files, and packages.
 Modifying existing passwords.
 Modifying messaging settings.
For information on configuring the Security logger, see webMethods Audit Logging Guide.
A service that functions as an event handler for a Security event should use the
pub.event:security specification as its service signature. For more information about the
pub.event:security service, see the webMethods Integration Server Built-In Services Reference.
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 event handlers that send notification about users opening sessions on the server.
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: 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 IntegrationServer_directory\lib
directory.
Working with Transaction Events

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 400.
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.
16 Building Services that Retry
 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
 Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
 Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Overview
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), 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 155.
 If the service functions as a trigger service (the service is invoked by a trigger), you
must configure the Transient error handling properties for the trigger. For more
information about configuring retry for Broker/local triggers, see the Publish-Subscribe
Developer’s Guide. For information about configuring retry for JMS triggers, see Using
webMethods Integration Server to Build a Client for JMS.
 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.
Name Description
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.
Step Description
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
Step 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.
Step Description
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.
17 webMethods Flow Steps
 BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
 INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
 LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
 MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
 REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
 SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
BRANCH
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
Name1
if the value of choice is ‘Name1’
Name2
if the value of choice is ‘Name2’
Name of the
switch field is NameN
choice if the value of choice is ‘NameN’
$null
if choice does not exist or has
a value of ‘$null’
no label
if the value of choice is an
empty string “ “
$default
Otherwise
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

Child1
if the expression of first child is true
Child2
if the expression of second child is true
Evaluate
labels is set to
true ChildN
if the expression of nth child is true
$default
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
Properties
The BRANCH step has the following properties.
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
Timeout Optional. Specifies the maximum number of seconds that this step
should run. If this time elapses before the step completes, Integration
Server issues a FlowTimeoutException and execution continues with
the next step in the service.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%. The
variable you specify must be a String.
If you do not need to specify a time-out period, leave Timeout blank.
For more information about how Integration Server handles flow step
timeouts, refer to the description of the
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 Specifies whether or not you want the server to evaluate labels of child
labels 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.
Conditions that Will Cause a BRANCH Step to Fail

 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.
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 Optional. Specifies the text of the exception message that is displayed
message 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%. The variable you specify must be a String.
Examples of When to Use

 Exit an entire flow service from within a series of deeply nested steps.
 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.
INVOKE
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.

If you want to use the value of a pipeline variable for this property,
type the variable name between % symbols. For example,
%expiration%. The variable you specify must be a String.

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).
Service Required. Specifies the fully qualified name of the service to invoke.
Validate input 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.
Validate output 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.
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.
LOOP
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

No
more input
array
input is members?
an array
Yes
get next
member of child child child
input array
Properties
The LOOP step has the following properties.

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,
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 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.
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.
MAP
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 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, Integration Server issues
a FlowTimeoutException and execution continues with the next step in the
service.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%. The
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
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 233.
REPEAT
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 child child child
reps = reps + 1
wait for Repeat

repeat reps < Count ? condition Exit
Yes Yes met? No
interval
No
Exit
Properties
The REPEAT 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
run. If this time elapses before the step completes, Integration Server
issues a FlowTimeoutException and execution continues with the next
step in the service.
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 re-
execute the child steps as long as the specified Repeat on condition is true.
the variable name between % symbols. For example, %servicecount%. The
Repeat Optional. Specifies the number of seconds the server waits before re-
interval executing the child steps. Specify 0 (zero) to re-execute the child steps
without a delay.
the variable name between % symbols. For example, %waittime%. The
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.
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.
SEQUENCE
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

If exit condition If exit condition
First... is not met... is not met...
child child child
Properties
The SEQUENCE 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.
run. If this time elapses before the step completes, Integration Server issues a
FlowTimeoutException and execution continues with the next step in the
service.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%. The variable
you specify must be a String.
Exit on Required. Specifies when to exit the SEQUENCE step.
Specify this value... To...
FAILURE Exit the sequence when a child step fails. (Execution

continues with the next flow step in the flow service.)
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.
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.
If Exit on is set to DONE, conditions that will cause a failure include:
18 Regular Expressions
 What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

 Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
 Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
What Is a Regular Expression?

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
symbol… To…
( ) 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.
| 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’.
Use this
symbol… To…
\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.
\t Match a tab character.
Example doc.p[/\twebMethods/].text
‘webMethods’ preceded by a tab character.
Use this
symbol… To…
\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’.
\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.
Use this
symbol… To…
\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 unit-
separator 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’.
- 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’.
19 Supported Data Types
 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

 Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 444
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 java.lang.String[ ]

array.
String table A two-dimensional String java.lang.String[ ][ ]
array.
Document A data structure that is a com.wm.data.IData
container for other
com.wm.util.Values
variables. Documents can
contain variables of any For more information, see the
other data type. The webMethods Integration Server
contents of a document Java API Reference.
(IData object) are stored as
key/value pairs where the
variable name is the key.
Document list A one-dimensional array com.wm.data.IData [ ]
of IS document types
com.wm.util.Values [ ]
(IData [ ]or Values [ ]).
com.wm.util.Table
Document A document whose Reference to an existing object
reference structure is defined by an which implements the
IS document type. com.wm.data.IData interface or
a reference to an existing
com.wm.util.Values object.
Document A document list whose Reference to an existing object
reference list structure is defined by an which implements the
IS document type. 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 Any subclass of java.lang.Object.
fall into any of the data
Example java.io.InputStream
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 An array of any subclass of
unknown type. java.lang.Object.
Example java.io.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
Services Reference.
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 279.
Java Classes for Objects

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.
 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. java.lang.Boolean[ ]
byte Signed integer. The value must be java.lang.Byte

greater than or equal to –128 but
less than or equal to 127.
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 java.lang.Character[ ]

array.
date Date and time. java.util.Date
date list A one-dimensional date array. java.util.Date[ ]
double Double-precision floating point java.lang.Double

number.
double list A one-dimensional double array. java.lang.Double[ ]
float Standard-precision floating point java.lang.Float

number.
float list A one-dimensional float array. java.lang.Float[ ]
integer Signed integer. The value must be java.lang.Integer

greater than or equal to -
2147483648 but less than or equal
to 2147483647.
integer list A one-dimensional integer array. java.lang.Integer[ ]
long Signed integer. The value must be java.lang.Long

greater than or equal to
–9223372036854775808 but less
than or equal to
9223372036854775807.
long list A one-dimensional long array. java.lang.Long[ ]
Data Type Icon Description Java Class

short Signed integer. The value must be java.lang.Short
greater than or equal to -32768 but
short list A one-dimensional short array. java.lang.Short[ ]
XOPObject A field in a SOAP message that is com.wm.util.XOPObject

to be sent/received as a streamed
MTOM attachment.
Note: Integration Server only

supports this Java wrapper type
for Web services.
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 281.
How webMethods Developer Supports Tables

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, 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.
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 An array variable that is The link defines the length of the
variable empty (the variable does not array variable; that is, it contains
have a defined length) one element and has length of one.
The first (and only) element in the
array is assigned the value of the
scalar variable.
value [empty] value

A scalar An array variable with a The length of the array is preserved
variable defined length and each element of the array is
assigned the value of the scalar
variable.
value X value
Y value
Z value

An array A scalar variable The scalar variable is assigned the
variable first element in the array.
X [empty] X
Y
Z

An array An array variable that does The link defines the length of the
variable not have a defined length 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.
X [empty] X
Y Y
Z Z

An array An array variable that has a The length of the source array
variable defined length 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.
X A X
Y B Y
Z C Z
No link occurs.
V A
W B
X C
Y
Z
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:
If you link... To...
DocumentList1 StringList1
String1
Where the value of DocumentList1 is... Then the value of StringList1 is…
DocumentList1 StringList1
a
DocumentList1 [0] b
c
String1
a
DocumentList1 [1]
String1 b
DocumentList1 [2]
String1 c
20 Conditional Expressions
 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
 Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
 Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
 Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Overview
webMethods Integration Server provides syntax and operators that you can use to create
expressions for use with the BRANCH step, pipeline mapping, and triggers.
 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 180
 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 225.
 For Broker/local 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.
 For JMS triggers, you can create local filters to further limit the messages a JMS
trigger processes. A filter specifies criteria for the contents of the message body.
Integration Server applies a local filter to the message after the JMS trigger receives
the message from the JMS provider. If the message meets the filter criteria, Integration
Server executes the trigger service specified in the routing rule.
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 463.
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 /regularExpression/ Pattern-matching string. Use the following

Expression syntax for pattern matching of variable values:
variableName = /regularExpression/
For more information about regular expressions,
see Appendix 18, “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 variableName Variable name. For information about how to use
this syntax to address children of other variables
–OR–
or elements of array variables, see “Addressing
%variableName% Variables” on page 460.
Example Explanation
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" Literal string. Use this value type to compare the
value of a variable to a string.
–OR–
'string'
Example Explanation
“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.
Example Explanation
%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"
Example: %myBoolean%=="true"
The string constant in the expression is case insensitive. For
example, the expressions %myBoolean%=="true" and
%myBoolean%=="tRUe" are equivalent.
Byte "xx"
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"
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 variableName Evaluates to true if the specified variable exists and

exists has a non-null value.
This example... Evaluates to true if...
customerID The customerID variable exists and

is not null.
Variable !variableName Evaluates to true if the specified variable does not
does not exist or is null.
exist
!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.
Operators
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
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 Broker/local 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).
 If you use a standard relational operator to compare numbers in fields of type String,
Integration Server treats the contents in the field as numbers. To stop Integration
Server from treating the value as a number, you can put quotes (' or '') around the
variable name in the expression. For example %'var1'%=%'var2'%.
The following table identifies the standard relational operators you can use in
expressions and filters.
Operator Syntax Description
= a=b Equal to.

customerID = "webMethods" The value of the customerId

variable is “webMethods.”
== a == b Equal to.
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<b Less than.
quantity < 5 The value of the quantity variable

is less than 5.
companyID < "Acme" The value of the companyID
variable is less than Acme.
<= a <= b Less than or equal to.
unitPrice <= 100 The value of the unitPrice variable

is less than or equal to 100.
companyID <= "Acme" The value of the companyID
variable is less than or equal to
Acme.
Lexical Relational Operators

You can use the lexical relational operators to create filters that compare string values.
Keep the following points in mind when using the lexical operators:
 When evaluating filters that contain lexical operators, the Integration Server uses the
locale collating sequence specified on the Broker to compare the values of the strings.
The behavior of lexical operators depends on whether a locale is set for the Broker. If
no locale is specified, the lexical relational operators behave like the standard
relational operators.
Note: To set the filter collation locale, use the Broker user interface to select the
Broker Server for which you want to change the locale. On the Broker Server
Information screen, select Change Broker Server Filter Collation Locale. Then, on the
Change Filter Collation Locale screen, in the New Locale list, select the locale you
want to use. Restart the Broker Server for the change to take effect.
 If you use a lexical operator to compare strings in an expression (such as in a

BRANCH step or in a pipeline link), the Integration Server treats the lexical operators
as if they were standard relational operators.
 If you use a lexical operator to compare a value that is not a string with another string
value, the Integration Server treats the non-string value as an empty string (that is, "").
For example, in the expression (%myInt% L_EQUALS ""), the %myInt% variable is
declared to be of type integer. This expression always evaluates to true because
%myInt% contains an integer value that the Integration Server treats as an empty string
("") when it evaluates the expression.
 If you use a lexical operator to compare numbers in fields of type String, Integration
Server treats the numbers as strings.
 Filters that use lexical relational operators to compare string values will be saved with
the trigger subscription on the Broker. Filters that use standard relational operators to
compare string values will not be saved on the Broker.
 When you view filters on the Broker user interface, a lexical operator appears as its
equivalent standard operator. For example, the expression %myString% L_EQUALS
"abc" appears as myString=="abc".
The following table describes the lexical operators that you can use in filters.
Operator Description
L_EQUALS Lexical equal to.

%myString% L_EQUALS "abc" The value of the

myString variable is
abc.
L_NOT_EQUALS Lexical not equal to.
%myString% L_NOT_EQUALS "abc" The value of the

not abc.
L_LESS_THAN Lexical less than.
%myString% L_LESS_THAN "abc" The value of the

less than abc.
L_LESS_OR_EQUAL Lexical less than or equal to.
%myString% L_LESS_OR_EQUAL "abc" The value of the

less than or equal to
abc.
Operator Description
L_GREATER_THAN Lexical greater than.

%myString% L_GREATER_THAN "abc" The value of the

greater than abc.
L_GREATER_OR_EQUAL Lexical greater than or equal to.
%myString% L_GREATER_OR_EQUAL "abc" The value of the

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.
%color% = "blue" | The value of the color variable

%color% = "red" is blue or red.
|| expr || expr Logical OR. True if either of the expressions is true.

totalPrice > 1000 || The value of the totalPrice

customerID = 'Favorite variable is greater than 1000 or
Customer'
the value of the customerID
variable equals Favorite
Customer.
or expr or expr Logical OR. True if either of the expressions is true.
creditCardNum = $null or The value of the creditCardNum

cardExpireDate = $null variable is null or missing or if
or cardExpireDate <=
the value of the cardExpireDate
orderDate
variable is null or missing or if
the value of the cardExpireDate
variable is less than or equal to
the value of the orderDate
variable.
& expr & expr Logical AND. Both expressions must evaluate to true for the
entire condition to be true.
%customerID% = 'Favorite The value of the customerID

Customer' & %sku% = variable is Favorite Customer
'WM001'
and the value of the sku
variable is WM001.
&& expr && Logical AND. Both expressions must evaluate to true for the
expr entire condition to be true.
quantity >= 20 && The value of the quantity

totalPrice >= 100 variable is greater than or
equal to 20 and the value of the
totalPrice variable is greater
than or equal to 100.
and expr and Logical AND. Both expressions must evaluate to true for the
expr 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
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 =, ==, !=, <>, >, >=, <, <=
4 and, &, &&
5 or, |, ||
Note: To override the order in which expressions in a condition are evaluated, enclose
the operations you want evaluated first in parentheses. webMethods Integration
Server evaluates expressions contained in parentheses first.
Addressing Variables
In an expression, you can refer to the values of variables that are children of other
variables and refer to the values of elements in an array variable. To address children of
variables or an element in an array, you need to use a directory-like notation to describe
the position of the value.
Use this notation… To…
variableName Address a variable.

Example: state
Variable state.
variableName/childVariableName Address the child variable of a
variable (such as a field in a
document).
Example: %buyerInfo/state%
Variable state within IS document type
buyerInfo.
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.
Use this notation… To…
%"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.
Notes:
 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 449.
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/ Address a variable named Date/Time in the document
Time"% variable purchaseOrder.
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 Address a variable named phone(cell) in the document

(cell)"% variable address(work).
%"Date\\Time"% Address a variable named Date\Time.
Typing Special Characters in Expressions

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)
Important! When you use variable names with special characters in expressions or
filters, you must enclose the variable name in " " (quotation marks).
Rules for Use of Expression Syntax with the Broker

When you create filters for documents in Broker/local trigger conditions, keep in mind
that some syntax that is valid on Integration Server is not valid on Broker. When you save
a Broker/local trigger, Integration Server and Broker evaluate the filter to make sure that
it uses proper syntax. If the syntax is valid on Broker, Broker saves the subscription and
the filter. If the syntax is invalid on Broker, Integration Server automatically removes the
filter before the Broker saves the subscription. The filter will only be saved on Integration
Server.
Note: 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 Broker considers invalid. Broker saves the expressions it
considers valid but does not save the expression containing invalid syntax.
(Integration Server saves all the expressions.)
Keep the following points in mind when writing filters for Broker/local 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 =, ==, !=, <, >, <= and >=) 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 user interface 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, eventtype L_EQUALS “addEmployee”
symbols, or words the Broker considers tax% < 5
restricted or reserved
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.
No comparison operators "fieldName"

"!fieldName"
A standard relational operator to %myString% < "yourString"

compare fields of type String
A lexical relational operator to compare %price% L_LESS_THAN 50
fields that are not of type String
A field of type String compared with a "stringName" > 12
numeric value
Operators other than =, ==, !=, or <> to myBoolean <= "true"
compare an Object constrained as a
Boolean with a value
An Object constrained as a Boolean myBoolean = "stringFieldName"
compared with a field of type String
Note: Expressions that check an Object
constrained as a Boolean for a true or false
value should include “true” or”false” as
part of the filter. The string constant in the
expression (“true” or “false”) is case
insensitive.
A $null token %fieldName% = $null
Regular expressions that contain back fieldName = /^(a|b)\1$/

references
Regular expressions that use quantifiers /a{1}/
other than +, ?, and *
/a{1,5}/
Regular expressions that use extended fieldName = /\w/
metacharacters
21 jcode tags
 jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

 jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
21 jcode tags
jcode Template
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)
{
// --- <<IS-START(Service1)>> ---
// --- <<IS-END>> ---
return;
}
public static void Service2 (IData pipeline)
{
// --- <<IS-START(Service2)>> ---
// --- <<IS-END>> ---
return;
}
// --- <<IS-START-SHARED>> ---
// --- <<IS-END-SHARED>> ---
}
21 jcode tags
jcode Example
The following is a complete example of properly commented Java source code.
Sample Code—IData
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)
21 jcode tags
* 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)
{
// --- <<IS-START(createAccount)>> ---
// [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");
// 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();
// --- <<IS-END>> ---
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)
{
// --- <<IS-START(getAccount)>> ---
// [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
// [o] -- field:0:required phone
IDataCursor idc = pipeline.getCursor();
if(idc.first("id"))
{
try
{
String id = IDataUtil.getString(idc);
21 jcode tags
IData data = getAccountInformation(id);

idc.last();
idc.insertAfter ("account", data);
}
catch (Exception e)
{
throw new ServiceException(e.toString());
}
}
idc.destroy();
// --- <<IS-END>> ---
}
/**
* == 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.
*/
// --- <<IS-START-SHARED>> ---
private static Vector accounts = new Vector();
private static IData getAccountInformation (String id) {
throw new RuntimeException ("this service is not implemented yet");
}
// --- <<IS-END-SHARED>> ---
}
21 jcode tags
22 Validation Content Constraints
 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
 Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
 Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Overview
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).
Content Types
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 19,
“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.

Constraining Facets
boolean True or false.
Constraining Facets
pattern
Example
true, 1, false, 0
byte A whole number whose value is greater than or equal to –128 but
Constraining Facets
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.
Constraining Facets
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
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.
Constraining Facets
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.
Constraining Facets
Example
8.01, 290, -47.24

double Double-precision 64-bit floating point type.
Constraining Facets
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.
Constraining Facets
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.
Constraining Facets
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.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
float A number with a fractional part.
Constraining Facets
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.
Constraining Facets
Example
---24 indicates the 24th 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.
Constraining Facets
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.
Constraining Facets
Example
--09-24 represents September 24th

gYear A specific year in the Gregorian calendar. Values must match the
following pattern:
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.
Constraining Facets
Example
2001 indicates 2001
gYearMonth A specific month and year in the Gregorian calendar. Values must
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
Coordinated Universal Time or to indicate the difference between
the time zone and coordinated universal time.
Constraining Facets
Example
2001-04 indicates April 2001
hexBinary Hex-encoded binary data.
Constraining Facets
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.
Constraining Facets

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.
Constraining Facets
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.
Constraining Facets
int A whole number with a value greater than or equal to
-2147483647 but less than or equal to 2147483647.
Constraining Facets
Example
-21474836, -55500, 0, 33123, 4271974
integer A positive or negative whole number.

Constraining Facets
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.
Constraining Facets

long A whole number with a value greater than or equal to
–9223372036854775808 but less than or equal to
9223372036854775807.
Constraining Facets
Example
-55600, -23, 0, 256, 3211569432
Name XML names that match the Name production of XML 1.0 (Second
Edition).
Constraining Facets
NCName Non-colonized XML names. Set of all strings that match the
NCName production of Namespaces in XML.
Constraining Facets
negativeInteger An integer with a value less than or equal to –1.
Constraining Facets
Example
-255556, -354, -3, -1
NMTOKEN Any mixture of name characters. Represents the NMTOKEN

attribute type from the XML 1.0 Recommendation.
Constraining Facets
NMTOKENS Sequences of NMTOKENS. Represents the NMTOKENS attribute
type from the XML 1.0 Recommendation.
Constraining Facets

nonNegativeInteger An integer with a value greater than or equal to 0.
Constraining Facets
Example
0, 15, 32123
nonPositiveInteger An integer with a value less than or equal to 0.

Constraining Facets
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.
Constraining Facets
Example
MAB-0907
positiveInteger An integer with a value greater than or equal to 1.

Constraining Facets
Example
1, 1500, 23000
short A whole number with a value greater than or equal to -32768 but
Constraining Facets
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.
Constraining Facets
Example
MAB-0907
time An instant of time that occurs every day. Values must match the
following pattern:
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 Coordinated
Universal Time or to indicate the difference between the time zone
and coordinated universal time.
Constraining Facets
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.
Constraining Facets
unsignedByte A whole number greater than or equal to 0, but less than or equal
to 255.
Constraining Facets
Example
0, 112, 200

unsignedInt A whole number greater than or equal to 0, but less than or equal
to 4294967295.
Constraining Facets
Example
0, 22335, 123223333
unsignedLong A whole number greater than or equal to 0, but less than or equal
to 18446744073709551615.
Constraining Facets
Example
0, 2001, 3363124
unsignedShort A whole number greater then or equal to 0, but less than or equal
to 65535.
Constraining Facets
Example
0, 1000, 65000
Constraining Facets
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 If you also entered possible
variable at run time. 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 The maximum number of digits to fractionDigits must be less than
the right of the decimal point. For or equal to totalDigits.
example, the fractionDigits of the
value 999.99 is 2.
length The precise units of length If you specify length, you
required for the variable value. cannot specify either
minLength or maxLength.
maxExclusive The upper bound of a range of maxExclusive must be greater
possible values. The range than or equal to minExclusive.
excludes the value you specify. The
You cannot specify
variable can have a value less than
maxInclusive and maxExclusive
but not equal to maxExclusive.
for the same content type.
maxInclusive The upper bound of a range of maxInclusive must be greater
possible values. The range than or equal to minInclusive.
includes the value you specify. The
You cannot specify
variable can have a value less than
maxInclusive and maxExclusive
or equal to maxInclusive.
maxLength The maximum units of length maxLength must be greater
permitted for the variable value. than or equal to minLength.
Constraining Facet Description Usage Notes

minExclusive The lower bound of a range of minExclusive must be less than
possible values. The range does or equal to maxExclusive.
not include the value you specify.
You cannot specify
The variable can have a value
minInclusive and minExclusive
greater than but not equal to
minExclusive.
minInclusive The lower bound of a range of minInclusive must be less than
possible values. The range or equal to maxInclusive.
includes the value you specify. The
You cannot specify
variable can have a value greater
minInclusive and minExclusive
than or equal to minInclusive.
minLength The minimum units of length minLength must be less than or
permitted for the variable value. equal to maxLength.
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.
totalDigits The maximum number of decimal totalDigits must be greater
digits allowed in a value. For than or equal to fractionDigits.
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
of the following:
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.
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.
23 Validation Errors and Exceptions
 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
 Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
 Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
 IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Overview
This appendix describes the following:
 Validation errors
 Validation exceptions
 Errors and warnings that may occur while generating an IS schema
Validation Errors
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
[ISC.0082.9447] Value does not conform to datatype.
Cause: The value does not match the specified content
type.
DT-002
[ISC.0082.9460] No matching enumeration value.
Cause: The value is not an item listed in the enumeration
field.
DT-003
[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.

DT-004
[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.
DT-005
[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.
DT-006
[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.
DT-007
[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.
DT-008
[ISC.0082.9491] Value is less than minInclusive.
Cause: The value is less than the value specified in the
minInclusive field.
DT-009
[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.
DT-010
[ISC.0082.9493] Value is greater than maxInclusive.
Cause: The value is greater than the value specified in the
maxInclusive field.
DT-011
[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.
DT-012
[ISC.0082.9448] Value does not match pattern.
Cause: The value does not match the pattern specified in
the pattern field.

DT-013
[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.
DT-Binary001
[ISC.0082.9293] No matching choice value
Cause: The binary value is not an element listed in the
choices field.
DT-Binary002
[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.
DT-Binary003
[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.
DT-Binary004
[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.
DT-Boolean001
[ISC.0082.9246] Value does not conform to datatype
Cause: The value is not a Boolean.
DT-Decimal001
Cause: The decimal value is not an element listed in the
choices field.
DT-Decimal002
Cause: The value is not a parsable decimal.
DT-Decimal003
[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.

DT-Decimal004
[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.
DT-Decimal005
[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.
DT-Decimal006
[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.
DT-Double001
Cause: The double value is not an element listed in the
choices field.
DT-Double002
Cause: The double value is less than the value specified in
the minimum exclusive or minimum inclusive field.
DT-Double003
Cause: The double value is greater than the value
field.
DT-Double004
Cause: The value is not a parsable double.
DT-Float001
Cause: The float value is not an element listed in the
choices field.
DT-Float002
Cause: The float value is less than the value specified in

DT-Float003
Cause: The float value is greater than the value specified
in the maximum exclusive or maximum inclusive field.
DT-Float004
Cause: The value is not a parsable float.
DT-Int001
Cause: The integer value is not an element listed in the
choices field.
DT-Int002
Cause: The integer value is less than the value specified in
DT-Int003
Cause: The integer value is greater than the value
field.
DT-Int004
Cause: The value is not a parsable integer.
DT-INTEGER001
Cause: The integer value is not an element listed in the
choices field.
DT-INTEGER002
Cause: The value is not a parsable integer.
DT-INTEGER003
Cause: The integer value is less than the value specified in
DT-INTEGER004
Cause: The integer value is greater than the value
field.

DT-Long001
Cause: The long value is not an element listed in the
choices field.
DT-Long002
Cause: The long value is less than the value specified in
DT-Long003
Cause: The long value is greater than the value specified
DT-Long004
Cause: The value is not a parsable long.
DT-List001
Cause: The sequence of values in the list is not an element
in the choices field.
DT-List002
Cause: Size of the list is less than the value specified in the
minimum length field.
DT-List003
Cause: Size of the list is greater than the value specified in
the maximum length field.
DT-List004
[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.
DT-RecurringDuration001
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.
DT-STR001
Cause: The string value is not an element listed in the
choices field.
DT-STR002
Cause: The size of the string, in characters, is less than the
value specified in the minimum length field.
DT-STR003
Cause: The size of the string, in characters, is greater than
the value specified in the maximum length field.
DT-STR004
[ISC.0082.9307] Does not match pattern(s)
Cause: The string value does not match the pattern
specified in the pattern field.
DT-Time001
Cause: The time value is not an element listed in the
choices field.
DT-Time002
Cause: The time value is less than the value specified in

DT-Time003
Cause: The time value is greater than the value specified
DT-Time004
Cause: The time value does not match the pattern
specified in the pattern field.
DT-TimeDuration001
Cause: The time duration value is not an element listed in
the choices field.
DT-TimeDuration002
Cause: The time duration value is less than the value
field.
DT-TimeDuration003
Cause: The time duration value is greater than the value
field.
DT-TimeDuration004
Cause: The time duration value does not match the
pattern specified in the pattern field.
DT-TimePeriod001
[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.
DT-TimePeriod002
Cause: The time period value is not an element listed in
the choices field.
DT-TimePeriod003
Cause: The time duration value is less than the value
field.

DT-TimePeriod004
Cause: The time duration value is greater than the value
field.
NV-001
[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.
NV-002
[ISC.0082.9002] Unable to retrieve root element
Cause: XML document is empty.
Response: Check that the document is being submitted
properly.
NV-003
[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.
NV-004
[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.
NV-005
[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.

NV-006
[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.
NV-007
[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
[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.
NV-009
[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.

NV-010
[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
[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.
NV-012
[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.
NV-013
[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.

NV-014
[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
[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.
NV-016
[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.
NV-017
[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.

NV-018
[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
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.
VV-003
[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 (one-
dimensional 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 one-
dimensional array (list). The variable it is being validated
against is a two-dimensional array (table).
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.
Validation Exceptions
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

Real time and Cause: The object to be validated does
[ISS.0062.9021] object is null design time not exist in the pipeline.
Response: Link an XML node or
document variable to the object
variable in Service In.
Real time and Cause: The IS document type or IS
[ISS.0062.9022] %NSName% - design time schema specified for the conformsTo
object does not exists 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.
Real time and Cause: The object to be validated is
[ISS.0062.9024] webMethods design time not one of the types supported by
Integration Server does not validation.
support this type of validation
(may or may not support in Response: Currently, only XML,
the future) pipeline, and document (IData object)
validation is supported.

Design time Cause: The min length is either not a
[ISS.0062.9202] Invalid: parsable number or conflicts with max
minLength 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
[ISS.0062.9203] Invalid: parsable number or conflicts with
maxLength 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
[ISS.0062.9211] Invalid regular expression.
Regular Expression:
Expression Response: Modify the pattern and
make sure that it is Perl regular
expression.
Design time Cause: The specified minInclusive value
[ISS.0062.9212] Invalid: is invalid. For example, the
minInclusive 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
[ISS.0062.9213] Invalid: value is invalid. For example, the
minExclusive minExclusive value for a variable with
also be a short.
Response: Make sure the minExclusive
content type.

Design time Cause: The specified maxInclusive
maxInclusive maxInclusive value for a variable with
also be a short.
Response: Make sure the maxInclusive
content type.
Design time Cause: The specified maxExclusive
maxExclusive maxExclusive value for a variable with
also be a short.
Response: Make sure the maxExclusive
content type.
Design time Cause: The value of a constraining
[ISS.0062.9230] Invalid scale facet has an invalid scale.
Response: Examine the constraining
facet values to make sure the values
do not conflict.
Design time Cause: The value of the minInclusive
[ISS.0062.9231] Exceeds constraining facet exceeds the value
precision: minInclusive specified for totalDigits.
minInclusive or totalDigits to make sure
the values do not conflict.
Design time Cause: The value of the minExclusive
precision: minExclusive specified for totalDigits.
minExclusive or totalDigits to make sure
Design time Cause: The value of the maxInclusive
precision: maxInclusive specified for totalDigits.
maxInclusive or totalDigits to make sure

Design time Cause: The value of the maxExclusive
precision: maxExclusive specified for totalDigits.
maxExclusive or totalDigits to make sure
Design time Cause: A content type constraint is
[ISS.0062.9235] Invalid defined in terms of the collective set
enumerated item 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.
Design time Cause: Invalid condition. The
[ISS.0062.9302] Maximum is maximum value is less than the
less than minimum minimum value.
(maximum < minimum)
Response: Change the maximum or
minimum value to eliminate the
conflict.

Design time Cause: The minimum value is out of
[ISS.0062.9303] Minimum is the valid range for the content type.
out of range (Valid range is
from lowerBound to Response: Change the minimum value
upperBound) (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
[ISS.0062.9304] Maximum is is out of the valid range for the
out of range (Valid range is content type.
from lowerBound to
upperBound) 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.
IS Schema Generation Errors and Warnings

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 256. For more
information about creating a flow service, see “Creating a New Flow Service” on
page 135.
Code Message and Description

CONV-001
[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 Software AG Software AG Global Support.
DTDC-001
[ISC.0082.9501] DTD is empty
Cause: The DTD does not contain any information.
Response: Make sure that the DTD is valid.
DTDC-002
[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.
DTDC-003
[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.
DTDC-005
[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.

XSDC-001
[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.
XSDC-002
[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
[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
Schema definition.
XSDC-004
[ISC.0082.9706] Declaration not found
Cause: An error. An element declaration or attribute declaration is
missing from the XML Schema definition.
XSDC-005
[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
Schema definition.
XSDC-006
[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
[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.
XSDC-009
[ISC.0082.9713] Unable to resolve QName
Cause: Incorrect QName.
Response: Check the value of the QName.
XSDC-080
[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.
XSDC-081
[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: If the schema you are using to generate a document type
contains a recursive complex type definition, select the Generate complex
types as document types option when you create a new document type
from an XML Schema in Developer.
Index
Symbols adding
_env field 267 folders 135
! 457 packages 78
!= 454 transformers 235
" 462 variables to pipeline link 232
( 462 addressing
) 462 variables in expressions and filters 460
/ 462 variables with special characters 461
\ 462 alarm events
& 458 definition of 386, 399
&& 458 reasons generated 399
% 462 uses of 399
‡ 283 all content model 249
< 455 Allow unspecified fields option 280
<= 455 and operator 459
<> 454 annotating source code for jcode 344
= 454 anonymous type definitions 249
== 454 any attribute declaration 248
> 454 any element declaration 248
>= 454 anyURI content constraint 473
| 457 API for Java services 338
|| 458 applying
$xmldata 373 conditions to links 225
constraints to variables 279, 472
A areas of Developer window
behavior and operation 35
access control 118
editor 31
ACLs
focus 35
assigning to elements 118, 121
general layout 25
assigning to packages and folders 121
Navigation panel 26
checking for services 119
Properties panel 33
defined 118
Recent Elements tab 31
element creation, view, and deletion implications
resizing 37
126
Results panel 35
inheritance 123
switching perspectives 38
locking implications 125
UDDI Registry tab 29
requirements for using Developer 22
zooming 37
testing and debugging implications 125
arithmetic services 235
viewing on a server 124
array variables
actions, performing on IS elements 36
default behavior for linking 444
adapter notifications
definition of 444
described 268
guidelines for linking 224
guidelines for moving and copying 55
linking to or from array variables 222, 444
adapter services, retry behavior 409
Index
linking to or from scalar variables 222, 444 Evaluate labels property 183
linking to transformers 238 specifying default step 185
assigning specifying label value 181
default value to a variable 228 specifying switch variable 181
replication services 92 switch value 180
shutdown services 92 using conditional expressions 183
startup services 92 using in a flow 180
universal names to services 157 using SEQUENCE as a target of 186
values to pipeline variables 227, 228 using with regular expressions 181
variable values to a variable 229 breakpoints
version numbers to packages 85 and the Trace Into command 313
attribute clearing from flow steps 314
declaration 248 clearing from transformers 314
reference 248 listing all 315
audit data, when generated 161 locating in flow services 315
audit events overview 313
definition of 386, 399 point when processing halts 313, 314
when generated 161 removing 315
Audit level property 168 setting in flow services 313
auditing setting on a flow step 313
configuring 159 setting on a transformer 314
failed and successful services 162, 166 Broker
failed services 162 filter collation locale 455
for errors 165 filter rules 463
for recovery, described 167 Broker document type, creating publishable
for resubmission purposes 165 document type from 265
long-running services 167 Broker document types
service retry 155 using to create publishable document type 265
services 159 Broker/local trigger
use cases 165 definition of 27
auditing options Broker/local triggers
setting for a service 167 creating filters for 448
browser clients
B creating 365
base64Binary content constraint 473 invoking services from 366, 367
blank labels in BRANCH steps 184 testing from 304
blue links, in the Pipeline tab 223 building
booleans event handler sample 396
content constraint 473 event handlers 396
in filters, Broker restrictions 464 flow services 130
BRANCH step built-in services
branching on empty values 184 for arithmetic operations 235
branching on expressions 183 for date/time transformations 235
branching on null values 184 for document (IData object) validation 287
branching on switch value 180 for pipeline validation 288
creating 188 for remote services 178
creating a multi-step child for 186 for string manipulation 235
definition of 132, 416 for XML validation 288
Index
invoking 178 COM objects

throwExceptionForRetry 156 invoking as services 352
byte content constraint 473 using with webMethods components 352
COM services
C creating 352
C/C++ clients com.wm.app.b2b.server.ISRuntimeException class
creating 358, 359 156
creating a make file 359 combining Trace and Step commands 307
C/C++ services commands
compiling with a make file 347 Disable Step 316, 317
creating 347, 348 Enable Step 316, 317
caching Load Pipeline Locally 324
definition of 146 Reset 307
elements to improve Developer performance 72 Restore Pipeline from Server 324
services not suited for 147 Restore Pipeline Locally 324
services suited for 147 Save Pipeline from Server 324
setting 149 Save Pipeline Locally 322
using prefetch 148 Save Pipeline to Server 322
call stack 302 Set Breakpoint 313
catch sequence, in service retry 409 Step 306, 310, 311
changing Step Into 306, 310, 311
level of a step 175 Step Out 310, 311
passwords 41 Trace 306, 308
position of a step 174 Trace Into 306, 308, 309
child flows Trace to Here 306, 308, 309
described 175 comments for jcode 344
stepping in/out of child flows 311 Comments property, definition 176, 420
tracing 309 compiling
choice content model 249 C/C++ services 351
circular dependencies, between packages 89 error in Java compiler location 339
class files Java services 339, 345
location of 342 services with Developer 339
clearing services with jcode 346, 347
breakpoints on flow steps 314 specifying the Java compiler 339
breakpoints on transformers 314 complex type definition
client applications all content model 249
creating browser-based 365 anonymous 249
creating C/C++ 358 choice content model 249
creating Excel 363 described 249
creating Java 356 empty content 249
creating Visual Basic 360 expanding as inline IS document type 260
closed documents, described 280 generating as separate IS document types 260
closing a session on webMethods Integration Server mixed content 249
39 recursive structures 260
coded services, about 332 sequence content model 249
collapsing composite mode (jcode) 347
transformers 242 conditional expressions
white space 484 addressing variables 460
Index
addressing variables with special characters 461 context-sensitive menus 36

lexical operators 455 Control steps
logical operators 457 BRANCH 132, 180
operator precedence 459 EXIT 132, 202
standard relational operators 453 LOOP 132, 198
syntax 449 REPEAT 132, 190
using with pipeline links 225 SEQUENCE 132, 196
using with the BRANCH step 183 converting string lists to document (IData object) lists
conditional links 221
creating 227 copying
described 225 by reference, definition of 217
disabling 318 by value, definition of 217
conditions elements from the Results panel 301
applying to links 225 IS elements 53
disabling on links 318 pipeline values 230
connecting to webMethods Integration Server 23, 39 set values 230
constraining facets transformers 241
applying 283 creating
described 279, 483 code for Java services 339
for pipeline validation 472 event filters 391
constraints event filters for services 394
content 246, 473 event handler sample 396
definition of 279 event handlers 396
for IS schemas 246 flow services 134, 135
for XML validation 246 folders 135, 348
structural 246 IS elements 47
viewing for variables 283 IS schemas 251
content constraints Java services with an IDE 343
applying to variables 279 Java services with C/C++ 347
constraining facets 279, 483 Java services with Developer 335, 338
editing for simple types 254 Java services with Visual Basic 352
for String variables, definition of 473 Java services with your own IDE 341
for validation 473 links to array variables 444
for variables, definition of 279 links to document (IData object) variables 220
for XML validation 246 packages 78
in IS schemas 246 specifications for C/C++ services 348
in IS schemas, definition of 246 version numbers for packages 85
content models cursors 333
all 249 customizing content types 282
choice 249
empty 249 D
mixed 249 dagger symbol, next to variable icon 283
sequence 249 data transformations, definition of 208
content types data types
applying to variables 280 icons to represent 137
constraint symbol 283 linking with Pipeline tab 220
customizing 282 supported by webMethods Integration Server 440
specifiying constraining facet values 283 tables 443
Index
data validation declaring

allowing undeclared variables 280 input and output parameters 137
applying constraints 279 input for a service 138
benefits of 278 output for a service 139
blueprints for 278 default value, assigning to a pipeline variable 228
closed variables 280 defining packages 78
content constraints 279 deleting
definition of 278 breakpoints on transformers 314
document (IData object) validation 287 event subscriptions 395
errors 488 IS elements 59
exceptions 291, 502 links between variables 225
input/output validation packages 84
definition of 284 dependencies, package
performing via Input/Output tab 285 identifying 88
performing via INVOKE step properties 286 removing 90
open variables 280 dependents
pipeline validation 288 checking when renaming IS elements 49
requiring variable existence 280 confirming before deleting elements 49
structural constraints 279 finding service and document (IData object) 66
types of 278 safeguards for updating 50
XML validation 288 details perspective 38
date content constraint 474 Developer window, toolbar 30
date conversion services 235 Developer. See webMethods Developer
dateTime content constraint 474 dimensionality, definition of 239
DCOM objects directories
invoking as services 352 Java services 341
using with webMethods Integration Server 352 Disable Step command 316, 317
debug level, setting on server 327 disabling
debugging flow services a condition placed on a link 318
breakpoints 313 a flow step 316
combining trace and step 307 a transformer 317
disabling a single flow step 316 dispatch services
disabling a transformer 317 for COM 352
disabling conditions on links 318 for DCOM 352
dumping the pipeline to serveryyyymmdd.log 329 document (IData object) validation
enabling a single flow step 316 definition of 287
enabling a transformer 317 errors 488
modifying the pipeline 319 exceptions 502
overview 294, 305 performing 287
resetting debug mode 307 document data type 440
stepping into a child flow 311 document list data type
stepping into a transformer 312 converting from String list 221
stepping through a flow 306, 310 definition of 440
tracing a flow 306, 308 document reference data type
tracing into a child flow 309 creating 271
using server debug facility 326, 327 definition of 440
debugLog service 328 document reference list data type
decimal content constraint 474 creating 271
Index
definition of 440 supported data types 137

Document Type Definitions. See DTDs tabs 31
document types. See IS document types viewing and editing elements in 32
documentation element declaration 248
accessing for packages 83 element lock
creating for packages 82 copying, moving, and deleting 108
using effectively 17 removing. See unlocking elements
documents (IData objects) system lock 102
applying content constraints 472 user lock 102
assigning to a document or document list 256, element reference 248
271 elements (IS)
assigning to a specification 256 See also editor 49
benefits of 256 assigning ACLs 121
creating 256 caching to improve Developer performance 72
errors when creating from DTD or XML Schema copying 53
507 creating 47
finding dependents 49 cutting 53
linking 220 definition of 46
open and closed 280 deleting 59
pipeline validation 288 displayed in editor 31
printing 270 displayed in Navigation panel 26
using as service parameters 256, 270 displayed in Recent Elements tab 31
viewing in browser 270 displayed in UDDI Registry tab 29
double content constraint 475 double-clicking to open 51
DROP modifier 212, 231 editing 49
dropping values from the pipeline 231 exporting 84
DTDs finding dependents 49
creating documents (IData objects) from 256 finding in Navigation panel 62
creating IS document types from 258 finding unresolved references 68
creating IS schemas from 251 fully-qualified names 47
IS schema generation warnings 507 guidelines
duration content constraint 475 copying 53
creating 47
E deleting 59
edit perspective 38 general actions 50
editing moving 53
elements. See editor opening and closing 51
event subscriptions 394 renaming 57
flow services 130 help for properties 42
properties 34 locating in Navigation panel 33
Service property 177 locking 49
simple types in IS schema 254 moving 53
editor naming guidelines 48
described 31 overwriting when creating publishable document
help about 42 types 265
hiding and showing 37 pasting 53
inserting flow steps into 173 performing actions 50
resizing 37 performing actions on 36
Index
permissions 118 audit events

references 67 definition of 386, 399
renaming 57 definition of 386
saving 59 event behavior 388
single-clicking does not open 51 event handlers 388
unlocking 49 Event Manager command 389
viewing as HTML 49 exception events 386, 400
emailing XML to a service 382 filters 391
empty GD End events 400
content 249 uses 400
strings in filters 456 GD Start events 400
values, branching on 184 uses 400
Enable service audtiting options, described 161 guaranteed delivery events 386
Enable Step command 316, 317 JMS delivery failure events 386, 392
enabling JMS retrieval failure events 387, 392, 401, 402
flow steps 316 pattern strings 391
service auditing 161 port status events 387, 403
transformers 317 uses 403
end-to-end linking 234 replication events 387, 403
entering input for a service 296 uses 403
ENTITIES content constraint 475 run-time behavior 388
ENTITY content constraint 475 security events 387, 403
enumeration constraining facet 483 session end events 404
envelope field session events 387, 404
in publishable document types 267 uses 404
usage restrictions 267 session expire events 404
error auditing, described 165 session start events 404
error events 386 stat events 388, 405
error handling, in flow services 196 uses 405
errors subscriptions
data validation 488 creating 389
document (IData object) generation 507 creating filters for 391
flow service generation 507 deleting 395
IS schema generation 507 editing 394
pipeline validation 488 managing 389
Evaluate labels property 189 suspending 395
event filters viewing 394
creating 391 transaction events 388, 405
creating for services 394 Tx End events 405
event handlers uses 405
creating 396 Tx Start events 405
creating sample 396 uses 405
definition of 388 viewing subscriptions 395
stages of creating 396 events
Event Manager See also event handlers, Event Manager
alarm events creating filters 391
definition of 386, 399 creating filters for services 394
uses 399 deleting subscriptions to 395
Index
editing subscriptions to 394 filters

guaranteed delivery 400 addressing variables 460
subscribing to 389 addressing variables with special characters 462
suspending subscriptions to 395 allowed quantifiers 464
types of 386 back references 464
viewing subscriptions to 394 booleans in 464
Excel clients, creating 363 braces {} in 464
exception events checking for variable existence 464
definition of 386, 400 collation locale, specifying 455
exceptions comparing strings and numeric values 464
data validation 291, 502 comparison operators, missing 464
during a test 301 constrained Objects in 464
executing services from Developer 295 effect of locale 455
execution locale 149 extended metacharacters 464
Exit on property 196 lexical relational operators 455
EXIT step logical operators 457
creating 203 $null 464
definition of 132, 419 operators for 453
using in a flow 202 server performance 453
expanding complex types inline 260 standard relational operators 453
expanding transformers 242 syntax 449
explicit linking, definition of 214 syntax restrictions 463
explicit universal names 158 variables with special characters 461
exporting elements and packages 84 finding
expressions elements in Navigation panel 62
addressing variables 460 invoked services 65
addressing variables with special characters 461 service and document (IData object) dependents
branching on 183 66
operator precedence 459 unresolved pipeline references 69
operators for 453 unresolved references 68
syntax for 449 float content constraint 475
using for pipeline linking 225 flow services
extending the Java class 337 See also services, debugging flow services
extends (Java keyword) 337 breakpoints 313
caching to improve Developer performance 72
F creating 135
facets, See constraining facets debugging 305
failIfInvalid property 502 definition of 130
failure disabling a single step 316
of a flow step 196 disabling a transformer 317
of a REPEAT step 191 disabling conditions placed links 318
fields editing 130
content type constraint symbol 283 enabling a single step 316
dagger symbol 283 enabling a transformer 317
green squares 283 errors creating from DTD or XML Schema 507
optional symbol 283 inserting steps in a service 173
filter collation locale 455 maximum retry period 155
filtering events 391 printing 169
Index
response to failure 196 global declarations, in XML Schemas and DTDS

retrying 155, 156 247
stages of creating 134 gMonth content constraint 476
stepping in/out of child flows 311 gMonthDay content constraint 476
stepping in/out of transformers 312 Go To Breakpoint command 315
stepping through 310 Go To command (for services) 65
tracing 308 gray links, in the Pipeline tab 213
viewing in browser 169 green square, next to variable icon 283
flow steps grouping flow steps 196
BRANCH 132, 180 guaranteed delivery events
changing the level of 174 See also GD End events, GD Start events
changing the position of 174 compared to transaction events 400
definition of 131 definition of 386, 400
disabling 316 generating guaranteed delivery (GD) events 400
enabling 316 generating transaction (Tx) events 400
EXIT 132, 202 overview 400
failure of 196 when generated 400
grouping 196 guidelines
hierarchical order of 175 for assigning startup, shutdown, and replication
inserting into a flow service 173 services 91
INVOKE 131, 177 for creating IS document types 258
LOOP 132, 198 for elements
MAP 131, 205 creating 47
moving in a flow service 174, 175 deleting 59
parent/child relationships 175 moving and copying 53
properties 176 opening and closing 51
re-enabling 316 renaming 57
REPEAT 132, 190 working with 50
SEQUENCE 132, 196 for linking array variables 224
setting breakpoints on 313 for linking document (IData object) variables 220
folders, creating 135 for linking variables 215
frag mode (jcode) 346 for linking variables of different data types 220
FTPing XML to a service 379 for naming packages 78
gYear content constraint 477
G gYearMonth content constraint 477
GD End events
definition of 400 H
pub.remote.gd:end 400 hailmary mode (jcode) 347
uses of 400 hard-coding input variables 227
when generated 400 help, obtaining 42
GD Start events hexBinary content constraint 477
definition of 400 hiding and showing panels 37
pub.remote.gd:start 400 HTML, viewing elements in 49
uses of 400
when generated 400 I
gDay content constraint 476 ID content constraint 477
Generate Code command 357, 359, 361 IData objects
generating complex types as document types 260 creating 333
Index
definition of 332 input/output validation

getting data from 333 definition of 284
positioning cursors 333 performing via Input/Output tab 285
putting data in 333 performing via INVOKE step 286
using in a Java service 343 inserting
IDE INVOKE step 178
assigning a super class with 337 steps into flow services 173
creating source code in 335 transformers 235
defining private methods with 338 installing Java services 341
implementing interfaces with 337 int content constraint 478
importing Java packages 337 integer content constraint 478
in Developer 334, 335 Integrated Development Environment. See IDE
using other IDEs 341 Integration Server Administrator, unlocking elements
using the Java service editor 335 110
using the Shared tab 337 Integration Server. See webMethods Integration
identifying Server
package dependencies 88 interfaces
replication services 92 implementing in Java service 337
shutdown services 92 INVOKE step
startup services 92 Comments property 420
IDREF content constraint 478 creating 178
IDREFS content constraint 478 definition of 131, 420
implementing interface in Java services 337 finding 65
implements (Java keyword) 337 invoking built-in services 178
implicit linking invoking services on another server 178
described 213 Label property 421
for MAP steps 234 peforming validation via step properties 286
implicit universal names 158 Pipeline tab 209
import (Java keyword) 337, 343 Scope property 420
import mechanism, in XML Schemas 253 Service property 177, 421
importing Java packages 337, 343 using in a flow 177
include mechamism, in XML Schemas 253 Validate input property 421
index, array variables 223 Validate output property 421
Indexing tab. See linking array variables invoking
Input array property 199 built-in services 178
input variables remote services 178
declaring for a service 137, 138 services 178
declaring in a document (IData object) 256 services from a browser 366, 367
entering test values for 296 services on another server 178
hard-coding 227 IS document types
linking considerations 215 See also documents (IData objects)
linking in the pipeline 214 creating empty document types 257
loading values from a file 298 creating from Broker document type 265
saving values to a file 298 creating from DTD 258
input/output parameters creating from XML document 258
declaring for a service 137 creating from XML Schema 258
generating Java code from 339 described 256
Input/Output tab 140 editing 269
Index
expanding complex types inline 260 stages of development 335

generating complex types as document types 260 structure of 334
guidelines for creating 258 using with webMethods components 334
IS elements. See elements (IS) validating from 289
IS schemas jcode utility
appearance 246 composite mode 347
constraints 246 frag mode 346
content constraints 246 hailmary mode 347
creating 251 make mode 346
definition of 246 purpose of 342
editing simple types 254 source code samples 466
errors from generating 507 source code tags 344
generating multiple 253 update mode 347
import element 253 JMS delivery failure event 386, 392
include element 253 JMS retrieval failure events 387, 392
structural constraints 246 JMS trigger
using to validate an XML document 288 definition of 27
warnings from generating 507 journal events 387
ISRuntimeExceptions
description of 155 K
throwing in services 408 keyboard shortcuts 36
J L
Java classes for object and object list variables 441 L_EQUALS 456
Java clients, creating 356, 357 L_GREATER_OR_EQUAL 457
Java keywords L_GREATER_THAN 457
extends 337 L_LESS_OR_EQUAL 456
implements 337 L_LESS_THAN 456
import 337, 343 L_NOT_EQUALS 456
Java service editor 335 Label property
Java services definition 421
adding private methods to 338 for evaluating expressions 183
compiler location 339 for general use 176
compiling with Developer 339 for specifying the default BRANCH step 185
compiling with jcode 345 for targeting BRANCH steps 181
creating 338, 339 language content constraint 478
creating with an IDE 341, 343 length constraining facet 483
creating with Developer 335 lexical relational operators
extending the class of 337 conditional expressions 455
implementing interface in 337 definition of 455
importing packages into 337, 343 empty string 456
installing manually 341 locale 455
jcode requirements 344 non-string variables 456
location of class files 342 libs directory 348, 351
location of source files 342 link indices 223
publishing to the server 341 linking
required code 343 array variables 222
setting run-time options 341 default rules 444
Index
guidelines for 224 log files, audit log 160

to array variables 444 logging on to webMethods Integration Server 23, 39
to scalar variables 444 logical operators, definition of 453
to transformers 238 long content constraint 479
between document formats 234 LOOP step
conditional links 225 creating 200
considerations 215 creating nested loops 198
copying by reference 217 definition of 132, 422
copying by value 217 setting Input array 199
default behavior for arrays 224 setting Output array 200
deleting links between variables 225 using in a flow 198
different data types 220
disabling conditions on links 318 M
document (IData object) variables 220 make file
in a single view 234 creating 347
input variables 214 using to compile C/C++ services 351
output variables 215 make mode (jcode) 346
pipeline variables to service variables 213 MAP modifier
scalar variables to array variables 444 definition of 212
the pipeline 216 executing at run time 217
transformers 237 linking different data types 220
variables conditionally 225 linking from service output 215
variables explicitly 214 linking to service input 214
variables implicitly 213 MAP step
links debugging 312
blue colored 223 definition of 131, 424
deleting 225 disabling transformers 317
disabling conditions 318 enabling transformers 317
executing at run time 217 inserting transformers 235
gray colored 213 Pipeline tab 211
in Pipeline tab 213 transformers 234
Load Pipeline Locally command 324 using in a flow 205
loading using to initialize variables in a flow 205, 228
input values from a file 298 mapping. See linking
pipeline values from a file Max attempts property 157
into Results panel 324 maxExclusive constraining facet 483
with restorePipelineFromFile service 325 maximum retry period, definition of 155
locating a breakpoint 315 maximum retry period, description of 155
locking elements maxInclusive constraining facet 483
corresponding server files 112 maxLength constraining facet 483
description 102 maxOccurs threshold value, for validation 292
Java and C/C++ 105 memory
single element 105 reducing usage 72
system locking 106 running out of during validation 292
template service 106 menu bar, using to perform actions 36
unlocking. See unlocking elements metacharacters, in filters 464
VCS check in/check out 102 methods, adding to a Java service 338
viewing lock status 103, 107 minExclusive constraining facet 484
Index
minInclusive constraining facet 484 object variables, Java classes 441

minLength constraining facet 484 online help, obtaining 42
mixed content 249 open and closed documents 280
modifying the pipeline 212 open documents, described 280
moving opening a session on webMethods Integration
IS elements 53 Server 39
steps in a flow service 174 operations, performing on IS elements 36
steps within a flow 175 operators
conditional expressions and filters 453
N lexical relational operators 455
Name content constraint 479 logical 457
name transformations, definition of 208 precedence in expressions 459
namespace information (for services) relational 453
creating source file from 347 standard relational operators 453
location of 341 optional variables for validation 280
updating with jcode 346 or operator 458
namespaces out of sync publishable document types 269
usage in universal names 157 Output array property 200
XML namespace property 272 output templates
naming services 47 assigning to a service 142
Navigation panel definition of 142
described 26 output variables
help about 42 declaring 139
hiding and showing 37 declaring for a service 137
icons 26, 103 declaring in a document (IData object) 256
refreshing contents of 29 linking considerations 215
resizing 37 linking in the pipeline 215
toolbar 30 Overwrite Pipeline Value option 228
NCName content constraint 479
negativeInteger content constraint 479 P
NMTOKEN content constraint 479 packages
NMTOKENS content constraint 479 adding 78
nonNegativeInteger content constraint 480 assigning version numbers 85
nonPositiveInteger content constraint 480 copying 81
not operator 457 creating 78
notification, of server shutdown 41 creating circular dependencies 89
ns directory 341 cutting 81
$null definition of 76
in filters 464 deleting 84
in labels for BRANCH steps 184 dependencies, using with startup services 90
null, branching on 184 documenting 82
exporting 84
O identifying dependencies 88
Object data type importing into Java services 337, 343
definition of 441 moving 81
in filters 464 naming guidelines 78
Object list data type, definition of 441 pasting 81
object list variables, Java classes 441 reloading 83
Index
reloading vs refreshing 83 dropping variables from 231

removing dependencies 90 inspecting modifiers 69
required by Java services 343 linking 216
viewing details 79 array variables 222
viewing patch history 86 default rules 444
panels guidelines for 224
editor 31 input variables 214
Navigation 26 output variables 215
Properties 33 scalar variables, default rules 444
Recent Elements 31 transformers 237
Results 35 variables of different data types 220
switching perspectives 38 MAP step 205
UDDI Registry 29 modifying 319
parameters Overwrite Pipeline Value option 228
applying constraints 279 Perform Variable Substitution option 229
benefits of declaring 137 Pipeline In 209
declaring 137, 141 Pipeline Out 210
declaring for a service 138, 139 saving 321
parent/child relationships in a flow 175 saving from Results panel 322
passing XML to a service 372 saving with savePipelineToFile service 323
passwords Service In 209
changing 41 Service Out 210
requirements 41 SET VALUE modifier 227
patch history stages of 209
removal by Integration Server 87 validating 288
viewing for a package 86 validating via built-in services 288
pattern constraining facet 484 validating via Java service 289
pattern matching, in event subscriptions 391 viewing after run-time exception 303
Perform Variable Substitution option 229 viewing with Developer 299
Performance 164 Pipeline Editor. See Pipeline tab
performance impact, service auditing 164 Pipeline In 209, 211
permission pipeline modifiers
See also ACLs definition of 212
assigning to elements 118 DROP 212
Permissions property 122 MAP 212
perspectives of views 38 SET VALUE 212
pipeline Pipeline Out 210, 211
adding variables to 232 pipeline references
addressing variables 460 definition of 69
adjusting 212 finding 69
assigning values to 227 Pipeline tab 208
changing values 319 blue links (conditional link) 223
checking for variables 452 copying by reference 217
conditional linking 225 copying by value 217
copying values 230 default behavior for arrays 224
definition of 132 default linking rules 444
DROP modifier 231 deleting links between variables 225
dropping values 319 editing a MAP step 211
Index
editing INVOKE step 209 Output array 200

gray links (implicit link) 213 Permissions 122
inserting transformers 235 Repeat on 190, 191, 427
linking Scope 188, 420
array variables 222 Service 177, 179, 236, 421
default rules 444 setting for variables 272
guidelines for 224 Substitution groups 262
document (IData object) variables 220 Switch 181, 189
scalar variables, default rules 444 Timeout 188, 192
transformers 237 Validate input 179, 236, 421
variables 213 Validate output 179, 236, 421
overview 208 XML Namespace 272
printing 212 Properties panel
transformer movement 238 auditing a service 160
viewing in browser 212 described 33
pipeline validation flow step properties 176
definition of 288 help about 42
errors 488 hiding and showing 37
exceptions 502 patch history for packages 86
performing via built-in services 288 resizing 37
performing via Java service 289 run-time parameters 145
port status events pub.flow:getRetryCount service 157
definition of 387, 403 pub.flow:throwExceptionForRetry service 156
uses of 403 invoking 411
positiveInteger content constraint 480 pub.publish:envelope document type 267
posting XML to a service 376 pub.remote:invoke service 178
precision constraining facet 484 pub.remote.gd:end service 400
prefetch 148 pub.remote.gd:start service 400
preserve white space 484 pub.schema:validate service 287
printing pub.schema:validatePipeline service 288
documents (IData objects) 270 publishable document types
flow services 169 adapter notifications 268
Pipeline tab contents 212 creating from Broker document type 265
private methods, defining in Java service 338 defined 265
programming languages editing 269
creating services with 332 envelope field 267
supported 332 overwriting elements 265
properties synchronizing 269
Audit level 168 publishing services to the server 341
Comments 176, 420
definition of 176 R
editing 34 Recent Elements tab
Evaluate labels 189 described 29, 31
Exit on 196 help about 42
for transformers 236 hiding and showing 37
Input array 199 resizing 37
Label 176, 421 Record data type. See document data type
Label (for BRANCH steps) 181, 185 Record list data type. See document list data type
Index
Record Reference data type. See document REPEAT step

reference data type creating (on failure) 192
Record Reference List data type. See document creating (on success) 194
reference list data type definition of 132, 425
records. See document (IData object), IS document failure 191
types specifying the repeat condition 190, 191, 427
recursive complex types in XML Schemas 262 using in a flow 190
redefine mechanism, in XML Schemas 253 using to retry a failed step 191
re-enabling using to retry a successful step 194
flow steps 316 replace white space 484
transformers 317 replication events
referenced elements, importing during definition of 387, 403
synchronization 266 uses of 403
references replication services
finding 67 assigning 92
inspecting pipeline 69 definition of 91
refresh guidelines for assigning 91
difference from restoring a session 40 removing 93
Navigation panel contents 29 when to use 91
Recent Elements tab contents 31 requirements for passwords 41
regular expressions requiring variable existence for validation 280
creating event filters with 394 Reset command 307
definition of 432 resizing
operators 433 panels 37
using as a BRANCH label 181 window areas 37
using in a mask 432 Restore Pipeline from Server command 324
reinvoking services 165 Restore Pipeline Locally command 324
relational operators restorePipelineFromFile service 321, 324
definition of 453 restoring
lexical 455 pipeline values from a file
standard 453 into Results panel 324
types of 453 with restorePipelineFromFile service 325
reloading packages 83 sessions 40
remote servers, invoking services on 178 Results panel
remote services, invoking 178 copying elements from 301
removing described 35
breakpoints 315 general information 300
breakpoints from transformers 314 help about 42
package dependencies 90 hiding and showing 37
packages 84 resizing 37
replication services 93 saving results from 321
shutdown services 93 retried audit log status 155
startup services 93 Retry interval property 157
variables from the pipeline 231 Retry on ISRuntimeException category 157
renaming retry period, maximum 155
IS elements 57 retry, for service 155
transformers 243 retrying a flow step 190
Repeat on property 190, 191, 427 Run command 295
Index
Run in Browser command 304 overview 326

running out of memory, during validation 292 service auditing
running services from Developer 295 configuring 159
run-time exceptions 301 described 159
run-time settings 341 enabling 161
error auditing 165
S failed and successful services 166
Save Pipeline Locally command 322 including pipeline 163
Save Pipeline to Server command 322 performance impact 162, 164
savePipelineToFile service 323 specifying which states to log 161
saving use cases 165
changes to elements 59 Service In 209
elements (IS) 59 service log
input values to a file 298 configuring 159
test results using savePipelineToFile service 323 described 160
test results, overview 321 Service Out 210
scalar variables Service property
default behavior for linking 444 definition 421
definition of 444 definition of 177
linking to or from array variables 444 editing 177
scale constraining facet 483 for transformers 236
schema browser, definition of 247 renaming transformers with 243
schema details area, definition of 250 service retry
schema domains 251 adapter services 409
schema editor 246 audit log 155
schema processor, definition of 251 basic componenents 409
schema services configuring 155
for document (IData object) validation 287 example 412
for pipeline validation 288 overview 408
for XML validation 288 requirements 156, 408
Scope property, definition 420 restrictions 156
Send XML File command 305 throwing exceptions for 408
sending XML documents services
to a service 372 assigning universal names 157
via email 382 audit data
via FTP 379 enabling 161
via HTTP 376 when generated 161
sequence content model 249 auditing
SEQUENCE step configuring 159
as target for a BRANCH 186 enabling 161
definition of 132, 428 for recovery 167
setting exit condition 196 long-running services 167
using in a flow 196 options 167
server files, viewing for locked elements 112 caching to improve Developer performance 72
server. See webMethods Integration Server configuring retry 155
serveryyyymmdd.log file 327 creating event filters for 394
contents of 327 creating flow 135
dumping pipeline to 329 creating with Visual Basic 352
Index
execution locale 149 showing and hiding panels 37

finding dependents 49 shutdown services
finding invoked 65 assigning 92
input signature for trigger services 139 definition of 91
invoking built-in 178 guidelines for assigning 91
invoking on another server 178 removing 93
invoking on remote servers 178 when to use 91
locale policy 149 signature
naming 47 for trigger services 139
provided by webMethods Integration Server 178 of a service 332
reinvoking 165 simple types 248
retry exceptions 408 editing in IS schema 254
retryiing 156 single view linking 234
retrying adapter services 409 smtp, using to submit XML documents 382
stages of creating 134 source code
state information 145 compiling with C/C++ make file 351
testing and debugging 294 compiling with jcode 345, 346, 347
throwing retry exceptions 408 creating automatically for a Java service 339
transformers 233 creating from namespace information 347
validating input/output via Input/Output tab 285 creating in your own Java IDE 343
validating input/output via INVOKE step 286 creating Java 340
session location of 342
closing on webMethods Integration Server 39 tagging for jcode 344
opening on webMethods Integration Server 39 writing in C/C++ 350
restoring 40 writing in Developer 335
session end events source control system, integration with 102
definition of 404 Source field on Shared tab 338
session events Source tab. See Java service editor
See also session end events, session expire special characters
events, session start events in variable names 461
definition of 387, 404 typing in expressions 462
uses of 404 specifications
session expire events assigning to a service 275
definition of 404 benefits of 273
session start events creating 273, 274
definition of 404 definition of 273
Set Breakpoint command 313 finding dependents 49
SET VALUE modifier 212, 227 squares, green 283
copying 230 stack overflow, during validation 292
using in MAP step 228 standard relational operators
setting definition of 453
breakpoints on flow steps 313 using in filters 453
breakpoints on transformers 314 using in triggers 453
variable values 227 starting Developer 23
Settings tab. See Properties panel startup services
Shared tab 337 assigning 92
short content constraint 480 definition of 90
shortcuts, for toolbars 30 effect on package dependencies 90, 93
Index
guidelines for assigning 91 tabs

removing 93 Input/Output tab 140
when to use 90 Pipeline tab 208
stat events Schema tab. See schema editor 246
definition of 388, 405 selecting 31
uses of 405 Settings tab for services. See also Properties
state information for a service 145 panel 341
status events. See port status events Shared tab 337
Step command 306, 310, 311 tagging source code for jcode 344
Step Into command 306, 310, 311 templates
Step Out command 310, 311 assigning to a service 142
stepping through a flow 306, 310 definition of 142
string content constraint 481 test perspective 38
String data type, definition of 440 test results
String list data type changing pipeline values 319
converting to document list 221 copying 301
definition of 440 loading 321
String table data type 440 saving 321
strings viewing 299
copying by reference 217 testing services
transformation services 235 entering test input 296
structural constraints from a browser 304
definition of 246, 279 from Developer 295
for validation 279 inspecting the pipeline 299
for XML validation 246 loading input values from a file 298
IS schemas 246 loading the pipeline 321
structural transformations overview 294
definition of 208 run-time exceptions 301
examples 221 saving input to a file 298
linking to resolve 220 saving the pipeline 321
subordinate flow steps. See child flows setting breakpoints 313
subscribing to events, overview 389 testing in debug mode 305
Substitution group property 262 viewing results 299
substitution groups 262 viewing the call stack 302
super class, defining in IDE 337 viewing the pipeline 303
suspending event subscriptions 395 XML document as input 305
Switch property 181, 189 threshold value, for maxOccurs 292
switch value, branching on 180 throw exception for retry 409
symbol time content constraint 481
for content type constraints 283 time conversion services 235
for optional variables 283 timeDuration content constraint 475
syntax for conditional expressions and filters 449 Timeout property
system locking for BRANCH step 188, 418
defined 102 for INVOKE step 179, 421
elements 106 for LOOP step 201, 423
for MAP step 424
T for REPEAT step 192, 193, 195, 426
tables, support of 443 for SEQUENCE step 429
Index
token content constraint 481 zooming in on 242

toolbar, Developer window 30 transient error, definition of 155, 408
toolbar, using to perform actions 36 trigger services, input signature requirements 139
totalDigits constraining facet 484 triggers
Trace command 306, 308 disabled when copied 54
Trace Into command 306, 308, 309, 310 filter syntax restrictions 463
and breakpoints 313 filters and relational operators 456
effect on breakpoints 313 lexical operators 453
Trace to Here command 306, 308, 309 testing 294
tracePipeline service 329 used with adapter notifications 268
tracing using standard relational operators 453
a flow 306, 308 try sequence, in service retry 409
into a child flow 309 Tx End events
transaction events definition of 405
See also Tx End events, Tx Start events uses of 405
compared to guaranteed delivery events 400 when generated 400
definition of 388, 405 Tx Start events
uses of 405 definition of 405
when generated 400 uses of 405
Transformer not found message 243 when generated 400
transformers type definitions
adding 235 anonymous 249
array variables 238 complex types 249
clearing breakpoints 314 simple types 248
collapsing 242
considerations 235 U
copying 241 Unicode, and Java source code 347
debugging 312 universal names
definition of 233 assigning to services 157
dimensionality mismatch 238 implicit vs explicit 158
disabling 317 local portion of name 157
enabling 317 namespace portion of name 157
expanding 242 removing from a service 159
inserting 235 unlocking elements
linking 237 more than one 108
linking array variables 238 system locked 111
movement in Pipeline tab 238 using Integration Server Administrator 110
output variables 237 using webMethods Developer 109
properties 236 unresolved references, finding 68
re-enabling 317 unsignedByte content constraint 481
renaming 243 unsignedInt content constraint 482
Service property 236 unsignedLong content constraint 482
services provided by webMethods 235 unSignedShort content constraint 482
setting breakpoints 314 update mode (jcode) 347
stepping in/out of child flows 312 URL, invoking services from 366, 367
Validate input property 236 user account on webMethods Integration Server 22
Validate output property 236
validating input and output 240
Index
V checking for existence 452

Validate input property 179, 236 content type constraint symbol 283
definition 421 copying by reference 217
Validate output property 179, 236 copying by value 217
definition 421 copying values in pipeline 230
validatePipeline service 288 declaring for a service 137, 138, 139
validating declaring in a document (IData object) 256
See also validation deleting links 225
documents (IData objects) 287 initializing values 228
from Java services 289 linked by blue line 223
input/output for transformers 240 linking 213
input/output via Input/Output tab 285 linking conditionally 225
input/output via INVOKE step 286 optional existence for validation 280
pipeline via built-in services 288 optional symbol 283
pipeline, overview 288 requiring existence for validation 280
service input/output 284, 285, 286 setting properties 272
XML documents 288 substitutions 229
validation using as Set Value 229
See also validating viewing applied constraints 283
allowing undeclared variables 280 XML Namespace property 272
applying constraints 279 VCS Integration feature, described 102
benefits of 278 version control system (VCS), integration with 102
blueprints for 278 version numbers, assigning to packages 85
constraining facets 483 View as HTML command 169, 212, 270
constraints, definition of 279 view perspectives 38
content constraints 473 viewing
definition of 278 assigned value of a variable 228
errors 291, 488 breakpoints list 315
exceptions 291, 502 elements in HTML 49
input/output 284 status of a locked element 103, 107
overview 278 test results 299
requiring variable existence 280 variable constraints 283
running out of memory 292 Visual Basic clients, creating 360
service input and output 284 Visual Basic services
stack overflow 292 creating 352
types of 278
XML validation 288 W
validation errors and error codes 488 warnings
validation services document (IData object) generation 507
pub.schema:validate 287, 288 flow service generation 507
pub.schema:validatePipeline 288 IS schema generation 507
value transformations, definition of 208 watt.server.invoke.maxRetryPeriod 156
variables watt.server.stats.pollTime property 403
adding to the pipeline 232 webMethods Developer
addressing in the pipeline 460 main window 25
applying constraints 279 online help 42
applying content constraints 472 starting 23
applying content types 280 toolbar 30
Index
webMethods Integration Server exceptions 502

access requirements for 22 IS schemas, overview 246
closing a session 39 performing 288
connecting to 23, 39 structural constraints 246
disconnecting from 39
logging on to 23 Z
notification of shutdown 41 zooming
opening a session 39 in a window 37
performing ACL checking 119 in on transformers 242
supported data types 440
webMethods Monitor 159, 165
webMethods Type Library 356, 360, 363
When to include input pipeline options, described
163
When to log options, described 161
whiteSpace constraining facet 484
win32.COM.dispatch:createObject 353
windows
layout 25
zooming 37
WmPublic package, definition of 178
X
XML documents
and $xmldata 373
converting to IData objects 372
creating documents (IData objects) from 256
creating IS document types from 258
creating IS schemas from 251
passing to a service 372
posting via HTTP 376
testing services with 305
XML Namespace property, described 272
XML Schema definitions
creating documents (IData objects) from 256
creating IS document types from 258
creating IS schemas from 251
import mechanism 253
include mechanism 253
IS schema generation warnings 507
recursive complex types 262
redefine mechanism 253
referenced by other XML Schemas 253
XML validation
content constraints 246
creating IS schemas 251
definition of 288
errors 488

8-2-SP2 Developer Users Guide PDF

Uploaded by

Copyright:

Available Formats

8-2-SP2 Developer Users Guide PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

8-2-SP2 Developer Users Guide PDF

Uploaded by

Copyright:

Available Formats

Title Page

Developing Integration Solutions

webMethods Developer User’s Guide

Document ID: DEV-UG-82SP2-20130301

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

1. Getting Started with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2. Managing Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 3

Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3. Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

5. Assigning and Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 5

How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

6 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

Including the Pipeline in the Service Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

7. Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 7

8. Mapping Data in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . . . . . . . . 245

8 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

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

10. Performing Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 9

Running Out of Memory During Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

11. Testing and Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

10 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

The Contents of the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

12. Building Coded Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

13. Creating Client Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 11

Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

14. Submitting and Receiving XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

12 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

15. Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

16. Building Services that Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 13

Adapter Services and Retry Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

A. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

C. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

14 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

Checking for Variable Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

F. Validation Content Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

G. Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 15

16 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

Deprecation of webMethods Developer

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 17

For webMethods... The documentation is downloaded to...

If you want to... Go to...

18 Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2

If you want to... Go to...

Developing Integration Solutions: webMethods Developer User’s Guide Version 8.2 19