Webmethods Designer Service Development Help 7 2

Title Page
webMethods Designer
Service Development Help
Version 7.2
December 2008
Copyright
& Docu‐
ment ID
This document applies to webMethods Designer Version 7.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 © 2008 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or their
suppliers. All rights reserved.
The name Software AG, webMethods, and all Software AG product names are either trademarks or registered trademarks of Software AG
and/or Software AG USA, Inc. Other company and product names mentioned herein may be trademarks of their respective owners.
Document ID: DES-ESBDH-72-20081212

Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
webMethods Central Documentation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
webMethods Advantage Bookshelf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Software AG Developer Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Part I. Service Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Before You Use Designer for Service Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Working with webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Working with Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Creating Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Fetching Server Definitions from an Integration Server . . . . . . . . . . . . . . . . . . . . . . . . 21
Importing Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Exporting Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Removing Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Editing Server Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Considerations for Process Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Setting a Default Server Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Placing a Server Definition Offline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Bringing a Server Definition Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Connecting to an Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Connecting to an Integration Server via Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Disconnecting from an Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Disconnecting from an Integration Server via Preferences . . . . . . . . . . . . . . . . . . . . . 29
Refreshing an Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Notification of Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Opening Integration Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Viewing Integration Server Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2. Working with Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

About Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Package Names and Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Guidelines for Naming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Guidelines for Working with Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Opening Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Closing Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Editing and Saving Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
webMethods Designer Service Development Help Version 7.2 3

Table of Contents
Configuring Dependency Checking for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Setting Dependency Checking Safe Guards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Guidelines for Moving and Copying All Types of Elements . . . . . . . . . . . . . . . . . . . . . 40
Guidelines for Moving and Copying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Guidelines for Copying Elements Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Notes for Moving and Copying Adapter Notifications and Related Elements . . . . . . . . 42
Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
What Is a Dependent? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Finding Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
What Is a Reference? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Finding References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Finding Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Searching for Elements in Package Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Locating Invoked Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Locating Referenced Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Linking Open Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Filtering Displayed Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Hiding or Displaying Automatically Generated Flow Services . . . . . . . . . . . . . . . . . . . . . . . 55
Creating Working Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Clearing the Designer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Exporting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Viewing an Elements Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3. Assigning and Managing Permissions for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

What Is an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
What Happens When a Client Runs a Service with ACLs? . . . . . . . . . . . . . . . . . . . . . 60
Is ACL Usage Required? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Creating ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
ACLS and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Default ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Assigning ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Viewing ACL Information for a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
How ACLs Affect Other Designer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
ACLS and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
ACLs and Running/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Troubleshooting ACL Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4 webMethods Designer Service Development Help Version 7.2

Table of Contents
4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Locking Elements in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Guidelines for Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Guidelines for Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Viewing Lock Status of Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Listing All of Your Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Unlocking Elements in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Automatically Unlocking an Element Upon Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Lock and Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5. Checking Elements In and Out of a VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

VCS Integration Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
VCS Integration Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Locking Locally vs VCS Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
System Locking and VCS Integration Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
VCS Integration: Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Hierarchical Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Working with Blaze Rules Services and Web Service Descriptors . . . . . . . . . . . . . . . . 87
Working with webMethods Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
About Unlocking Elements with Integration Server Administrator . . . . . . . . . . . . . . . . 89
Working with Java Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Copying Java Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Moving Java Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Labeling Java Services in the VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Adding Packages and Elements to a VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Modifying Elements that are in the VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Checking Out Packages and Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Checking In Packages and Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Reverting Changes to a Checked Out Package or Element . . . . . . . . . . . . . . . . . . . . . . . . 97
Getting the Latest Version from the VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Getting an Earlier Version from the VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Deleting Packages and Elements from the VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Table of Contents
Restoring Deleted Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Restoring a Deleted Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Restoring a Deleted Folder or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Copying and Moving Folders or Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Renaming Packages, Folders, and Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Viewing the History of a Folder or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6. Managing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Guidelines for Naming Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Documenting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Accessing Package Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Viewing Package Settings, Version Number, and Patch History . . . . . . . . . . . . . . . . . . . . . 114
Assigning a Version Number to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Copying Packages Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Copying Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Exporting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
About Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Identifying Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Removing Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Assigning Startup, Shutdown, and Replication Services to a Package . . . . . . . . . . . . . . . . 122
What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Assigning a Startup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Removing a Startup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
What Is a Shut Down Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Assigning a Shutdown Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Removing a Shutdown Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Assigning a Replication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Removing a Replication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
7. Building Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Package and Folder Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Declaring a Service Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Specifying Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Specifying Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Declaring Input and Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Using a Specification as a Service Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Using an IS Document Type to Specify Service Input or Output Parameters . . . . 135
Inserting Input and Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Table of Contents
Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Maintaining the State of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Specifying the Run-Time State for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Configuring a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Types of Services to Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Services Suited for Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Services that You Should Not Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Controlling a Service’s Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Specifying the Duration of Cached Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Using the Prefetch Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Configuring Caching of Service Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Specifying the Execution Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Configuring Services to Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Service Auditing Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Error Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Auditing for Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Auditing Long-Running Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Setting Auditing Options for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Assigning a Universal Name to a Service or Document Type . . . . . . . . . . . . . . . . . . . . . . . 149
Implicit and Explicit Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Assigning, Editing, or Viewing an Explicit Universal Name . . . . . . . . . . . . . . . . . . . . . 151
Deleting an Explicit Universal Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
The Universal Name Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Services You Use to Interact with the Universal Name Registry . . . . . . . . . . . . . . 153
Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

What Is a Flow Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
What Is the Pipeline? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Building Services Using the Tree Tab or Layout Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Changing the Position of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Changing the Level of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Setting Properties for a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Specifying the Service Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Invoking a Built-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Invoking a Service on Another Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Building an Invoke Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Table of Contents
The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Specifying the Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Specifying the Label Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Branching on an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Branching on Null and Empty Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Specifying a Default Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Using a SEQUENCE as the Target of a BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Building a BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Specifying the REPEAT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Setting the REPEAT Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Using REPEAT to Retry a Failed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Using REPEAT to Retry a Successful Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Using SEQUENCE to Specify an Exit Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Specifying the Input Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Collecting Output from a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Building a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Building an EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9. Mapping Data in Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

What Does the Pipeline View Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Pipeline View for an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Pipeline View for a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Linking Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Creating a Link Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
What Happens When Integration Server Executes a Link? . . . . . . . . . . . . . . . . . . . . . 201
Example of Copying By Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Preventing Pipeline Values from Being Overwritten . . . . . . . . . . . . . . . . . . . . . . . 203
Linking to Document and Document List Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Linking Variables of Different Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Converting a String List to a Document List in the Pipeline . . . . . . . . . . . . . . . . . . 205
Converting Two String Lists to a Document List in the Pipeline . . . . . . . . . . . . . . 206
Linking to and from Array Variables in the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Creating a Link to or from an Array Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . 209

Table of Contents
Deleting a Link Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Linking Variables Conditionally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Linking Multiple Source Variables to a Target Variable . . . . . . . . . . . . . . . . . . . . . 214
Applying a Condition to a Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Assigning Values to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Setting a Value for a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Copying Assigned Values Between Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . 216
Dropping Variables from the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Dropping a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Adding Variables to the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Adding a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Using Built-In Services as Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Inserting a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Linking Variables to a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Transformers and Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Example of Dimensionality Mismatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Validating Input and Output for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Copying Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Renaming Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Debugging Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
10. Running and Debugging Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Using Launch Configurations while Running and Debugging Services . . . . . . . . . . . . . . . . 229
Creating a Launch Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Supplying Input Values to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Entering Input for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Saving Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Loading Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Running a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
About Debugging Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
About Debug Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
About Debug Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
About Debug View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Debugging a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Stepping Through Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Stepping Through a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Stepping Into and Out of a Child Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Stepping Into and Out of a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Breakpoint States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Setting and Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Setting and Removing Breakpoints on Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . 246
Setting or Removing Breakpoints on a Transformer . . . . . . . . . . . . . . . . . . . . . . . 247

Table of Contents
Enabling and Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Skipping Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Disabling and Enabling Flow Steps and Transformers . . . . . . . . . . . . . . . . . . . . . . . . . 249
Disabling and Enabling Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Modifying the Pipeline while Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Changing Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Dropping Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Saving and Restoring the Pipeline while Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Saving the Pipeline while Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Saving the Pipeline to a File while Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Restoring the Pipeline while Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Loading a Saved Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Viewing Service Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Messages Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Call Stack Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Saving the Service Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Restoring the Service Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
11. Working With Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Creating a Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Adding Fields to an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . . 265
Creating an IS Document Type from an XML Document . . . . . . . . . . . . . . . . . . . 266
Creating an IS Document Type from a DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Creating an IS Document Type from an XML Schema . . . . . . . . . . . . . . . . . . . . . 268
Expanding Complex Document Types Inline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Generating Fields for Substitution Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Working with Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Creating a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Making a Document Type Publishable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
About the Associated Broker Document Type Name . . . . . . . . . . . . . . . . . . . . . . 275
About the Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
About Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . 278
Making Document Types Unpublishable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Specifying Document Storage Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Document Storage Versus Client Queue Storage . . . . . . . . . . . . . . . . . . . . . . . . . 281
Selecting Document Storage Type for a Publishable Document Type . . . . . . . . . 281
Specifying the Time to Live for a Publishable Document Type . . . . . . . . . . . . . . . . . . . 282
Setting the Time to Live for a Publishable Document Type . . . . . . . . . . . . . . . . . . 282
Specifying Validation for a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . 283
Setting Validation for an Individual Publishable Document Type . . . . . . . . . . . . . 284

Table of Contents
Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Important Considerations When Modifying Publishable Document Types . . . . . . . . . . 285
Deleting Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Deleting a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Synchronizing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Synchronization Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Synchronization Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Combining Synchronization Action with Synchronization Status . . . . . . . . . . . . . . . . . 290
Synchronizing a Single Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Synchronizing Multiple Document Types Simultaneously . . . . . . . . . . . . . . . . . . . . . . 293
Synchronizing Document Types in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Synchronizing Document Types Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Importing and Overwriting References During Synchronization . . . . . . . . . . . . . . . . . . 293
What Happens When You Overwrite Elements on the Integration Server? . . . . . 294
What Happens if You Do Not Overwrite Elements on the Integration Server? . . . 294
Testing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Creating a Launch Configuration for a Publishable Document Type . . . . . . . . . . . . . . 295
Testing a Publishable Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
About Universal Names and Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
12. Working with Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Creating a Document Reference or a Document Reference List Variable . . . . . . . . . . . . . 301
Assigning Properties to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Assigning XML Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Guidelines for Assigning XML Namespaces to Web Service Descriptors . . . . . . . 303
Assigning XML Namespaces and Prefixes to Variables . . . . . . . . . . . . . . . . . . . . . . . . 303
Assigning Display Types to String Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Considerations for Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Applying Constraints to a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Customizing a String Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Viewing the Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Part II. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
13. Integration Server Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
14. Service Development Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Adapter Service/Notification Error Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Flow Service Editor Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Package Navigator Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Publishable Document Type Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Table of Contents
15. Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Integration Server Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Event Manager Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Server ACL Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Server Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Package Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Package Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Package Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Package Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Package Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Package Startup/Shutdown Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Element Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Element Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Element Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Element General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Document Type Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Publication Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Universal Name Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Flow Step Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
JMS Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
General Properties for a Non Transactional JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . 336
General Properties for a Transactional JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Fatal Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Transient Error Handling with a Non Transactional JMS Trigger . . . . . . . . . . . . . . . . . 340
Transient Error Handling with a Transactional JMS Trigger . . . . . . . . . . . . . . . . . . . . . 342
Exactly Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
General Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
General Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Run Time Properties for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Transient Error Handling Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Audit Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Universal Name Properties for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Output Template Properties for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Transformer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
General Properties for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Variable Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
General Properties for Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Constraints Properties for a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Table of Contents
Web Service Connector Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Run Time Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Audit Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Universal Name Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Output Template Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Web Service Descriptor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Web Service Descriptor Operation Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Operation Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Body Element Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Header Element Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Fault Element Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Binder Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Web Service Descriptor Header Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 370
16. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Branching on Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
BRANCH Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Conditions that Will Cause a BRANCH Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
EXIT Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
INVOKE Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Conditions that Will Cause an INVOKE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
LOOP Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Conditions that Will Cause a LOOP Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
MAP Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Example of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
REPEAT Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
SEQUENCE Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Conditions that Will Cause the SEQUENCE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . 383

Table of Contents
17. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Java Classes for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
How Designer Supports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
18. Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Package Navigator View Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
UDDI Registry View Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Flow Step Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
19. Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Document Type Editor Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Flow Service Editor Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Package Navigator View Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Pipeline View Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Service Result View Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
UDDI Registry View Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Variables View Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Web Service Descriptor Editor Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
20. Supported and Unsupported Elements in webMethods Designer . . . . . . . . . . . . . . . . 405

Supported Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Unsupported Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

About This Guide
webMethods Service Development allows developers to manage packages, connect to
Integration Server, create services and other namespace elements, and to publish and
retract metadata. You can learn more by looking in Contents for Software AG Products >
webMethods Service Development Help.
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.
[ ] 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 (...).
Additional Information
You can find additional information about webMethods products at the locations
described below.
webMethods Central Documentation Directory

During product installation, you can download the webMethods product documentation
to a single directory called “_documentation.” This directory is located by default under
the webMethods installation directory.

About This Guide
webMethods Advantage Bookshelf

The webMethods Advantage Web site at http://advantage.webmethods.com provides
you with important sources of information about webMethods products:
 Troubleshooting Information. The webMethods Knowledge Base provides
troubleshooting information for many webMethods products.
 Documentation Feedback. To provide feedback on webMethods documentation, go to
the Documentation Feedback Form on the webMethods Bookshelf.
 Additional Documentation. You can find documentation for all webMethods products on
the webMethods Bookshelf.
Software AG Developer Community

Additional articles, demos, and tutorials are available on the webMethods portion of the
Software AG Developer Community. The various Developer Communities feature
technical information, useful resources, and online discussion forums, moderated by
Software AG professionals, to help you do more with webMethods technology.
With the Software AG Developer Communities, you can:
 Use the online discussion forums to exchange best practices and chat with other
experts.
 Expand your knowledge with product documentation, code samples, articles, online
seminars and tutorials.
 Link to external sites on open standards and many Web technology topics.
 See how other customers are streamlining their operations with technology from
Software AG.

I Service Development
webMethods Designer provides a set of Service Development features that you can use to
build, edit, and debug services and integration logic. It provides a collection of editors
and views in which you can develop the logic and supporting objects (referred to as
elements) for an integration solution. It also provides tools for running and debugging the
solutions you create.
Designer 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. Designer 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, Designer provides additional
editors and tools for creating various elements that support the execution of an
integration solution. For example, you use Designer to create the document types and
schemas used for data validation and to define triggers that launch the execution of
services when certain messages are received. Service Development is covered in the
following online help topics.
 “Before You Use Designer for Service Development” on page 18
 “Working with webMethods Integration Server” on page 19
 “Working with Elements” on page 33
 “Assigning and Managing Permissions for Elements” on page 59
 “Locking and Unlocking Elements” on page 69
 Checking Elements In and Out of a VCS
 “Managing Packages” on page 111
 “Building Services” on page 129
 “Building Flow Services” on page 155
 “Mapping Data in Flow Services” on page 193
 “Running and Debugging Flow Services” on page 229
 “Working With Document Types” on page 263
 “Working with Variables” on page 301

I Service Development
You will also find the following reference topics:
 “Integration Server Preferences” on page 313
 “Service Development Preferences” on page 315
 “Properties” on page 321
 “webMethods Flow Steps” on page 371
 “Supported Data Types” on page 385
 “Icons” on page 389
 “Toolbars” on page 395
 “Supported and Unsupported Elements in webMethods Designer” on page 405
Before You Use Designer for Service Development

Designer builds and edits services and other elements directly on a webMethods
Integration Server. To use Designer for service development, you must:
 Have access to an Integration Server on which you can build and debug 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 Integration Server.
 Create a server definition that defines the connection between Designer and
Integration Server.
If you do not have access to a Integration Server or you do not have an appropriate user
account or access rights, see your server administrator.
Related Topics
 “Working with Server Definitions” on page 19
 “Connecting to an Integration Server” on page 28

1 Working with webMethods Integration Server
webMethods Integration Server provides an environment for the orderly, efficient, and
secure, execution of services. It decodes client requests, identifies the requested services,
invokes the services, passes data to them in the expected format, encodes the output
produced by the services, and returns output to the clients.
Using Designer, you build and edit services, document types, and other elements directly
on an Integration Server. You connect Designer to Integration Server through server
definitions. A server definition specifies the location and characteristics of the Integration
Server to which Designer is connecting.
Related Topics
 “Connecting to an Integration Server” on page 28
 “Disconnecting from an Integration Server” on page 29
 “Refreshing an Integration Server” on page 30
 “Notification of Server Shutdown” on page 30
 “Opening Integration Server Administrator” on page 30
 “Viewing Integration Server Properties” on page 31
Working with Server Definitions

A server definition specifies the location and characteristics of an Integration Server to
which Designer connects. You connect to Designer through server definitions. You create
and view server definitions on the Window > Preferences > Software AG > Integration Servers
page.
Related Topics
 “Creating Server Definitions” on page 20
 “Fetching Server Definitions from an Integration Server” on page 21
 “Importing Server Definitions” on page 23
 “Exporting Server Definitions” on page 23
 “Removing Server Definitions” on page 24
 “Editing Server Definitions” on page 24

Creating Server Definitions

By default, a new Designer installation includes a single server definition named Default.
This server is marked as the default server and is configured to use localhost:5555.
If your Designer installation needs to connect to more Integration Servers, you can create
additional server definitions.
To create a server definition
1 In Designer
Window > Preferences
2 In the preferences navigation tree, select Software AG > Integration Servers.
3 Click Add.
4 In the Add Integration Server dialog box, enter the following information:
Field Description
Name Name to use for this Integration Server.
Host Host name or IP address of the Integration Server to connect to.
Port Port number to connect to on the Integration Server.
User Indicates the name of a valid user account on the Integration
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. Integration Server user
names are case sensitive.
Password The password for user. Use the exact combination of upper‐ and
lower‐case characters with which it was originally defined.
Integration Server passwords are case sensitive.
Connect Indicates whether Designer should connect to the Integration
immediately Server immediately after you add or edit a definition and click
OK on the Add Integration Server or Edit Integration Server
dialog box.
Connect at Indicates whether Designer should automatically connect to the
startup Integration Server at Designer startup.
Secure Indicates whether the session will be opened through HTTP or
Connection HTTPS. If you want to open an HTTPS session on the selected
server using the Secure Socket Layer (SSL), select this check box.
If you want to open an HTTP session on the server, clear this
check box.

5 To test this connection, click Verify Server.
6 Click OK.
By default, Designer will automatically connect to the Integration Server. If Designer
does not automatically connect to the server, click Connect on the Preferences page.
Related Topics
 “Setting a Default Server Definition” on page 26
 “Fetching Server Definitions from an Integration Server” on page 21
Fetching Server Definitions from an Integration Server

You can obtain a server definition by fetching it from another Integration Server.
For the fetch process to work, the WmDesigner package must be installed and running
on the other Integration Server, and the server definition you are trying to fetch must
have been previously defined on the copy of Designer running on the other server.
To fetch to an Integration Server definition from another Integration Server
1 In Designer
2 In the preferences navigation tree, select Software AG > Integration Servers
3 Click Fetch.
4 In the Fetch dialog box, enter the following information about the Integration Server
from which you want to fetch a server definition.
Field Description
Host Name or IP Host name or IP address of the Integration Server to connect to.

Address
Port Port number on which Integration Server listens for requests.
Secure Indicates whether to connect to Integration Server through an
Connection HTTP or HTTPS connection. Select the check box to connect
through an HTTPS connection.

Field Description
User The name of a valid user account on this server.
Use the exact combination of upper‐ and lower‐case characters
with which it was originally defined. Integration Server user
Note: The server is installed with a default user account called
“Developer” that has developer privileges.
Password The password for the user account in User. Use the exact
combination of upper‐ and lower‐case characters with which it
was originally defined. Integration Server passwords are case
sensitive.
5 Click Connect.
Designer populates the bottom half of the Fetch Integration Server Definitions dialog with
a list of server definitions available on the other Integration Server.
6 Select one or more definitions to fetch, and click OK.
Designer refreshes the Integration Servers page, this time including the fetched
definitions. Designer automatically tries to connect to the fetched servers.
7 For any server definitions that have the status No user or password, select the
definition, click Edit, supply the userid and password, and click OK.
Related Topics
 “Opening Integration Server Administrator” on page 30
 “Viewing Integration Server Properties” on page 31

Importing Server Definitions

You can import server definitions from a properties file. A properties file can contain one
or more server definitions.
The default properties file name is logicalServer.properties. It resides in the top level of
the Designer folder in the following directory:
<workspace_location>\.metadata\.plugins\com.softwareag.is.core. The file contains the
initial installed server definition, which specifies a host name and port of localhost:5555,
is named Default, and is marked as the default server.
You can use properties files to make existing server definitions available to other
Designer users in cases where it is not possible to fetch server definitions.
When you import servers definitions, you overwrite all existing definitions in your
workspace.
To import a server definition properties file
1 In Designer:
3 Click Import.
4 In the Open window, navigate to the .properties file you want to import.
5 Click OK to import the data from the selected .properties file into your Preferences >
Software AG > Integration Servers screen.
Related Topics
Exporting Server Definitions

You can export server definitions to a properties file. When you export server definitions,
you export all definitions in your workspace.
You can save the file with any name and in any location, but the file must be saved with a
.properties extension.
To export server definitions to a properties file
1 In Designer:
3 Click Export.

4 In the Save As dialog box, navigate to the folder where you want to save the server
definition you are exporting, and type a file name. You do not have to type the
.properties extension.
You can also click an existing .properties file if you want to overwrite it with the new
definitions.
5 Click OK to save the .properties file.
Related Topics
Removing Server Definitions
To remove a server definition
1 In Designer
3 Select the server definition you want to remove.
4 Click Remove.
Designer prompts you to confirm that you want to remove this server definition. If
this server definition is the default, Designer will remind you that you need to define
a new default after this server definition has been deleted.
5 If the server definition you deleted was the default, you need to define a new default.
For instructions on defining a default server definition, see “Setting a Default Server
Definition” on page 26.
Related Topics
Editing Server Definitions

You can change the properties of a server definition by editing it.
Sometimes there are changes on the associated Integration Server that require you to
update the server definition. For example, if the port number changes, you must update
the server definition to reflect that change.

Other times, you might decide to change the name of the server definition, or to change
whether Designer automatically connects to this Integration Server at Designer startup or
when the definition is updated.
If a server definition displays a status of No userid or password, you can edit the definition
to add the user and password.
For a detailed description of the fields you can change, see “Integration Server
Preferences” on page 313.
To edit a server definition
1 In Designer
3 Select the server definition that you want to edit.
4 Click Edit.
5 Enter new values in the fields you want to change.
6 In the Edit Integration Server dialog, click OK.
7 In the Preferences page, click OK.
Related Topics
Considerations for Process Development

If you will be working in Process Development, you might want to make the following
changes your server definitions to:
 Specify a server definition as the default.
 Place server definitions offline.
 Bring server definitions online.
Related Topics
 “Placing a Server Definition Offline” on page 26
 “Bringing a Server Definition Online” on page 27

Setting a Default Server Definition

By default, a new Designer installation includes a server definition named Default. This
server is marked as the default server and is configured to use localhost:5555. If a user
creates or edits a process and no server definitions are connected, Designer automatically
connects to the default server definition.
If you update the configuration so that a different server definition is the default, and a
user subsequently creates a step when Designer is not connected to an Integration Server,
Designer will use the new default server for the new steps. In contrast, Designer will
continue to use the original servers for existing steps.
There must be one and only one default Integration Server defined at all times.
To set a default server definition
1 In Designer
3 Check the Default box for the server definition you want to be the default.
Designer prompts you to verify that you want to replace the existing default with the
new one.
4 Click OK.
Related Topics
Placing a Server Definition Offline

Typically, when you work with Designer, it is connected to the Integration Servers
defined by the server definitions on the Integration Servers Preferences page. Process
Development users, however, can perform tasks without being connected to an
Integration Server. By placing a server definition offline, you can prevent Designer from
trying to connect to the associated server and prompting you for credentials.
When you select the Offline check box for a server definition, Designer terminates any
existing connections to the host:port combination specified in this definition. For
example, if server definition A and server definition B both specify localhost:5555,
selecting the Offline check box to the right of A will terminate the server connections for
both A and B.
Refer to the Process Development Help for more information.

To place a server definition in offline status
1 In Designer
3 Select the Offline check box to the right of server definition you want to take offline.
4 Click OK.
Related Topics
 “Bringing a Server Definition Online” on page 27
Bringing a Server Definition Online

Designer must be connected to an Integration Server so that you can view and update
Integration Server assets such as flow services, document types, JMS triggers, and Web
service descriptors. There may be times, however, when you find that a server definition
that you need to work with is offline.
To bring a server definition online
1 In Designer
3 Clear the Offline check box to the right of server definition you want to bring online.
4 If Designer issues a message stating that you must enter a username and password,
click the Edit button and provide the username and password.
5 Click OK.
Related Topics

Connecting to an Integration Server

When you connect to an Integration Server, you create a session on that Integration
Server. You maintain a session on that server until you exit Designer or disconnect from
the server. You can have open sessions on multiple servers at a time.
To connect to an Integration Server
1 In Package Navigator view, select the server to which you want to connect.
2 Right click, and select Connect to server.
Related Topics
 “Connecting to an Integration Server via Preferences” on page 28
Connecting to an Integration Server via Preferences

Designer must be connected to an Integration Server so that you can view and update
Integration Server assets such as flow services, document types, JMS triggers, and Web
service descriptors.
To connect to an Integration Server
1 In Designer:
3 On the Integration Servers page, select the server to which you want to connect and
click Connect.
Related Topics
 “Disconnecting from an Integration Server via Preferences” on page 29

Disconnecting from an Integration Server

While you have an open session on a server through Designer, you are using a licensed
seat for that server. At times when you are not actively using Designer, you may want to
close your session to free a seat on the server for others to use.
To disconnect from an Integration Server
1 In Package Navigator view, select the Integration Server from which you want to
disconnect.
2 Right click, and select Disconnect from server.
Related Topics
Disconnecting from an Integration Server via Preferences

While you have an open session on a server through Designer, you are using a licensed
seat for that server. At times when you are not actively using Designer, you may want to
close your session to free a seat on the server for others to use.
To disconnect from an Integration Server
1 In Designer:
3 On the Integration Servers page, select the server from which you want to disconnect
and click Disconnect.
Related Topics
 “Connecting to an Integration Server via Preferences” on page 28

Refreshing an Integration Server

Package Navigator view is not dynamically updated when other users lock, unlock, add,
delete, or rename elements on a server. You can refresh an Integration Server to reflect
any changes made to the contents of the servers with which you are working.
To refresh an Integration Server
1 In Package Navigator view, select the Integration Server you want to refresh.
2 Right click, and select Refresh.
Notification of Server Shutdown

If the server administrator shuts down the server on which you have an open session,
Designer does one of the following:
 If the server administrator specified a time delay before shutdown, Designer 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, Designer notifies you when the server has shut down.
 If the server administrator performed an immediate shutdown, Designer displays a
message stating that your connection to the server has been lost. (Designer also
displays this message if the network connection to the server is lost.)
Designer restores your connection to the server when the server restarts. If you did not
save your work before shut down occurred, Designer prompts you to save your work
after the connection is re‐established.
Opening Integration Server Administrator

There may be times when you need to perform administrator tasks on an Integration
Server.
To open Integration Server Administrator
 In Package Navigator view, right‐click the Integration Server for which you want to
open Integration Server Administrator and select Open Administration View.

Viewing Integration Server Properties
To view Integration Server properties
 In Package Navigator view, right‐click the Integration Server for which you want to
open Integration Server Administrator and select Properties.
Designer displays the Properties screen, from which you can display information
about the following areas of the Integration Server: Event Manager, Server ACLs,
Server Information, and Server Locked Elements. Refer to “Integration Server
Properties” on page 321 for a description of these properties.


2 Working with Elements
An element is an item that exists in the Package Navigator view in webMethods
Designer. Elements include folders, services, specifications, IS document types, triggers,
and IS schemas. In the Package Navigator view, servers and packages are not considered
to be elements.
Related Topics
 “About Element Names” on page 34
 “Creating New Elements” on page 34
 “Guidelines for Working with Elements” on page 36
 “Opening Elements” on page 37
 “Closing Elements” on page 37
 “Editing and Saving Elements” on page 38
 “Configuring Dependency Checking for Elements” on page 38
 “Moving and Copying Elements” on page 40
 “Renaming Elements” on page 44
 “Deleting Elements” on page 46
 “Finding Dependents and References” on page 47
 “Inspecting Pipeline References” on page 50
 “Finding Elements” on page 52
 “Filtering Displayed Elements” on page 54
 “Hiding or Displaying Automatically Generated Flow Services” on page 55
 “Creating Working Sets” on page 55
 “Caching Elements” on page 55
 “Exporting Elements” on page 57
 “Viewing an Elements Corresponding Server Files” on page 58

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. 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
Designer ensures that the fully qualified name of each element within the server is
unique. Depending on the action you are performing on the element, Designer
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, Designer copies the service and names the copy
checkOrder2_1.
Related Topics
 “Package Names and Element Names” on page 34
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.
Creating New Elements

When creating elements, keep the following points in mind:
 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,
Designer creates the element and names it Untitled.
 Designer 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 35.

To create a new element
1 In the Package Navigator view of Designer, click File > New and then click the element
you want to create.
You can also click Other to view all the elements that you can create in Designer. The
New dialog box appears. Click the type of element you want to create and then click
Next.
2 On the New Element dialog box, follow the prompts given by Designer for the type of
element you are creating.
3 When you have supplied all of the information that Designer needs to create the
element, click Finish. Designer refreshes the Package Navigator view and displays the
new element.
Related Topics
 “Guidelines for Naming Elements” on page 35
Guidelines for Naming Elements

Designer 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 (This does not apply to packages.)
 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, Designer 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.

Guidelines for Working with 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.
 Designer 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,
Designer makes the action unavailable for use. For example, Designer disables the
cut, copy, paste, and delete actions if you select a server. Designer 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 Designer encounters an error while performing
the specified action on one or more of the elements, Designer 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. If you configured Integration Server to work with a version control
system (VCS), you must first check out the element before editing it and then check it
back in.
 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, Designer 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 Elements
When opening elements from the Package Navigator view, keep the following points in
mind:
 Click an element to select it. To open an element in the editor, double‐click it.
 Double‐click a folder to expand or collapse the contents of the folder in the Package
Navigator view. To view the properties of a folder, click File > Properties.
 If you have enabled the Version Control System (VCS) Integration feature of
Designer, Designer 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 Package
Navigator view. This condition occurs because Designer checks the lock status of
each element within the expanded element in the Integration Server.
To open elements in the editor
 In Package Navigator view, double‐click the element you want to open.
Closing Elements
Keep the following points in mind when closing elements:
 You do not need to close elements when you exit Designer. Designer remembers
which elements were open and displays them when you restart Designer.
 If you close an element without saving changes made to the element, Designer will
prompt you to save changes.
To close elements in the editor
 Do one of the following:
To... Do this...
Close the active element (that is, the Click File > Close.

element whose tab is highlighted)
Close all elements Click File > Close All.

Editing and Saving Elements

To edit an element, you must first lock it (or check it out). You must also have Write access
to the element.
Changes that you make to an element are not written to Integration Server until you
explicitly save your work. If you attempt to close Designer, 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, Designer will prompt you to save changes first.
To save changes to elements
 Do one of the following:
To... Do this...
Save changes to the current element Click File > Save.

Save all elements you have edited, on Click File > Save All.
all servers
Related Topics
 “Locking Elements” on page 70
 “Checking Out Packages and Elements” on page 94
 “Checking In Packages and Elements” on page 95
 “Editing Document Types” on page 285
Configuring Dependency Checking for Elements

Designer automatically checks for dependents when you delete, rename, or move
elements in the Package Navigator view. This dependency checking acts as a safeguard
to prevent you from inadvertently affecting other elements on the Integration Server.
This is especially important during collaborative development on the same Integration
Server.
You can have Designer prompt you before deleting, moving, or renaming an element
with dependents. You can also have Designer update local references when pasting
elements.
Related Topics
 “Setting Dependency Checking Safe Guards” on page 39

Setting Dependency Checking Safe Guards

The dependency checking options are enabled by default.
To specify dependency checking safeguards
1 Click Window > Preferences.

2 In the Preference navigation tree, click Software AG > Service Development > Package
Navigator.
3 Under Preferences for the Package Navigator view, do the following:
Select... To...
Confirm before deleting Instruct Designer to notify you before deleting an element

used by other elements, such as flow services, IS document
types, specifications, or triggers.
If Designer finds elements that depend on the element
being deleted, Designer lists those dependents and
prompts you to delete the element anyway or cancel the
action. If you clear this check box, Designer deletes the
element without prompting you.
Prompt before updating Instruct Designer to alert you when dependents (that is,
dependents when other elements that use the selected element, such as flow
renaming/moving services, IS document types, or triggers) exist.
If dependents exist, Designer 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, Designer automatically updates
dependents without prompting you.
Update local references Instruct Designer to update references when copying and
when pasting multiple pasting a group of elements that refer to each other.
elements
If you clear this check box, Designer retains the original
references in the copied elements.
4 Click OK.

Moving and Copying Elements

You can move or copy elements between packages and, in most cases, across servers.
Related Topics
 “Guidelines for Moving and Copying All Types of Elements” on page 40
 “Guidelines for Moving and Copying Services” on page 40
 “Guidelines for Copying Elements Between Servers” on page 41
 “Notes for Moving and Copying Adapter Notifications and Related Elements” on
page 42
 “ACLs and Creating, Viewing, and Deleting Elements” on page 65
Guidelines for Moving and Copying All Types of Elements

 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 “Assigning
and Managing Permissions for Elements” on page 59.
 When you move or copy an element, Designer 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, Designer 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, Designer updates the references if you
have selected Update local references when pasting multiple elements preference. For
example, if you copy a folder that contains two services and one of the services
invokes the other, Designer will update the reference to the invoked service.
Guidelines for Moving and Copying Services

 When you move or copy a service, Designer does not move/copy any output
templates that are associated with that service.
 If you move a service, or a folder containing a service, Designer retains the service’s
explicit universal name. If you copy a service or a folder containing a service, Designer
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 a
Universal Name to a Service or Document Type” on page 149.

 When you move or copy a Java service, Designer automatically recompiles the service
and any Java services that remain in the source folder. When you delete a Java
service, Designer 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, Designer
cancels the entire move/copy action.
 When you move or copy a Java service, Designer 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.
Guidelines for 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, Designer 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.
 Designer 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.
 Designer does not automatically update references when copying across servers.
Therefore, if you are copying multiple elements from one server to another using
Designer 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, Designer
displays an error message stating that you are attempting to copy an unknown
element. Designer 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 the webMethods Integration
Server Administrator’s Guide for more information about this feature.

 When you move or copy a publishable document type to a destination on the same
server, the moved or copied document type remains publishable. When you copy a
publishable document type to a different server, Designer 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 “Working with Publishable Document Types” on
page 272.
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 Designer to move or copy the package containing
the publishable document type. For information about package replication, see
the webMethods Integration Server Administrator’s Guide.
Notes for 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, Designer 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, Designer alerts you that
the move/copy action cannot be completed.
 You cannot move or copy a listener or connection element.
Moving and Copying Elements
To move or copy elements
1 In the Package Navigator view, select the elements that you want to move or copy.
2 Do one of the following:
To... Click...
Move 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, Designer 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, Designer 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 Click Edit > Paste.
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, Designer 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, Designer 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, Designer 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 44.
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, Designer 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, Designer 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, Designer 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 using
Developer. (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 selected the Prompt before updating dependents when renaming/moving check box in

the Package Navigator preferences and any dependent elements on the current server
contain unsaved changes, Designer alerts you to save them. Select the elements and
click OK to save the changes or Cancel to cancel the entire move or copy action.
10 If the Move and Rename Dependencies dialog box appears, do one of the following:
To... Click...
Move the selected element and update references to Update Usages

dependent elements
Move the selected element in the Package Navigator view Ignore Usages
without updating references to dependent elements
Cancel the entire move action Cancel
For more information about dependency safeguards, see “Configuring Dependency
Checking for Elements” on page 38.
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 “Assigning and Managing Permissions for Elements” on
page 59.
 When you rename a folder, Designer 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, Designer reverts the element back to its original
name.
 When you rename an adapter notification, Designer 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.
 When you rename a publishable document type, Designer checks for dependents
such as triggers and services that use the publishable document type. (Designer
performs dependency checking only if you select the Prompt before updating dependents

when renaming/moving preference.) If Designer finds elements that use the publishable

document type, Designer gives you the option of updating the publishable document
type name in each of these elements. If you do not update the references, all of the
references to the publishable document type will be broken.
Important! You must manually update any services that invoke the pub.publish services
and specify this publishable document type in the documentTypeName or the
receivedDocumentTypeName parameter.
To rename an element
1 In Package Navigator view, select the element that you want to rename. Right‐click
the element and click Rename.
2 If the element you want to rename contains unsaved changes, Designer 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.
3 Edit the name and press ENTER.
If an element already exists with that name at the same level, Designer 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.
4 If you selected the Prompt before updating dependents when renaming/moving check box in
the Package Navigator preferences and any dependent elements on the current server
contain unsaved changes, Designer alerts you to save the elements that will be
affected by the rename action. Select the elements and click OK to save the changes or
Cancel to cancel the entire rename action.
5 If the Move and Rename Dependencies dialog box appears, do one of the following:
To... Click...
Rename the selected element in Package Navigator view 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
For more information about dependency safeguards, see “Configuring Dependency
Checking for Elements” on page 38.

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 “Assigning and Managing Permissions for Elements” on page 59.
 When you delete a folder or the last Java service in a folder, Designer 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, Designer 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.
 If you delete a publishable document type, Designer prompts you to keep or delete
the associated Broker document type.
 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
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.
To delete elements
1 In Package Navigator view, select the elements that you want to delete.
2 Select Edit > Delete.
3 If you have selected the Confirm before deleting check box in the Preferences dialog box
for Package Navigator view, do the following:
a If any elements on Integration Server have unsaved changes, Designer prompts
you to save changes. Select the elements whose changes you want to save and
click OK.
b If other elements are dependents of the elements you are deleting, Designer
indicates which items will be affected by the deletion.

c If you are deleting a publishable document type, Designer prompts you to keep or
delete the associated Broker document type. Do one of the following:
To... Do this...
Delete the publishable document type on Clear the Delete associated Broker

Integration Server but leave the document type on the Broker check
corresponding document type on the box.
Broker
Delete the publishable document type on Select the Delete associated Broker
Integration Server and the corresponding document type on the Broker check
document type on the Broker box.
d Click Continue to delete the selected elements.
4 If you did not select the Confirm before deleting preference and one of the elements that
you want to delete is a publishable document type, Designer prompts you to keep or
delete the associated Broker document type. Select the Delete associated Broker
document type on the Broker check box, if you want to delete the publishable document
type and the Broker document type. Click OK.
Related Topics
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 Designer, a dependent is an element that uses a selected element, and a reference
is an element that is used by a selected element.
Related Topics
 “What Is a Dependent?” on page 48
 “Finding Dependents” on page 48
 “What Is a Reference?” on page 49
 “Finding References” on page 50

What Is a Dependent?
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 the receivePO service.
This makes ServiceA a dependent of the flow service receivePO. If you delete receivePO,
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.
Note: Designer 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
Designer to find dependents of service B, service A will not appear as a dependent.
Finding Dependents
To find dependents of a selected element
1 In Package Navigator view, right‐click the element for which you want to find
references and select Find Dependents.
2 If any elements on Integration Server have unsaved changes, Designer prompts you
to save changes. Select the elements whose changes you want to save, and then click
OK.
Designer displays the dependents of the selected element on the Search view.
3 After Designer finds the dependents of the selected element, you may do either of the
following:
 To jump to an element in Package Navigator view, right‐click that element in the
results, and select Show In > Package Navigator.
 To see all dependents of a found dependent, click next to the item in the results
list.

What Is a Reference?
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 ServiceA. The elements receivePO, validate, ProcessPO, SubmitPO, and
PODocument 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 Package Navigator view 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 “Configuring Dependency Checking for Elements” on page 38.
Note: Designer 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
Designer to find references for service A, service B will not appear as a reference of A.

Finding References
To find references of a selected element
1 In Package Navigator view, right‐click the element for which you want to find
references and select Find References.
2 If any elements on Integration Server have unsaved changes, Designer prompts you
to save changes. Select the elements whose changes you want to save, and then click
OK.
Designer displays the references of the selected element on the Search view.
3 After Designer finds the references of the selected element, you may do either of the
following:
 To jump to an element in Package Navigator view, right‐click that element in the
results, and select Show In > Package Navigator.
 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 variable in a document reference or document reference list
in Pipeline view is linked to another variable, assigned a value, or dropped. 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 variable in the
document reference is linked to another pipeline variable, then that link is a pipeline
reference. In the following illustration of the Pipeline view, the link between PONum and
num is a pipeline reference.
Pipeline reference
This variable is a
reference to the
PODocument in the
Package Navigator view.
The link between

PONum and num is a
pipeline reference.

Pipeline references are also those locations where you modify the value of a variable in a
document reference or document reference list by assigning a value using or
dropping a value using on the Pipeline view toolbar. The following illustration of
Pipeline view identifies these types of pipeline references.
Examples of pipeline references
This dropped value ... this assigned value

and... are pipeline references.
When you edit an IS document type, the changes affect any document reference and
document reference list variables defined by that IS document type. The changes might
make pipeline references invalid. For example, suppose the input signature for ServiceA
contains a document reference variable POInfo based on the IS document type
PODocument. The IS document type PODocument contains the field PONum. In the pipeline
for ServiceA, you link the PONum field to another pipeline variable. If you edit the
PODocument IS document type by deleting the PONum field, the pipeline reference (the
link) for the field in the ServiceA pipeline is broken (that is, it is invalid) because the
pipeline contains a link to a field that does not exist.
When you edit an IS document type, you might want to check all dependent pipeline
modifiers for validity. You can use the 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.

Inspecting Pipeline References

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 assigned to document reference or document reference list variables in the
pipeline are not considered pipeline references. That is, when a value is assigned to a
document reference or document reference list variable using on the Pipeline view
toolbar, Designer does not treat the assigned value as a pipeline reference.
 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, Designer inspects references
across all packages on 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
 In Package Navigator view, right‐click the flow service or IS document type for which
you want to find invalid pipeline references and select Inspect Pipeline References.
The Search view 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.
After Designer finds the pipeline references of the selected element, you can jump to
an element in Package Navigator view. Right‐click that element in the results, and
select Show In > Package Navigator.
Finding Elements
You can find elements and fields within Designer using the following methods:
 Searching for elements in the Package Navigator view. 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.

 Locate an invoked service from the editor. You can highlight the location of an invoked

service in the Package Navigator view. This is especially helpful when working with
a flow written by another party or complex flows that make multiple invokes.
 Locate a referenced document type from the editor. You can highlight the location of a
referenced document type in the Package Navigator view. This is especially helpful
when working with services with complex signatures, mapping data, or working
with flow services written by other developers.
 Linking open editors. If you have a lot of elements open, you might want to quickly
bring the editor for an element to the top of the stack of open editor views.
Related Topics
 “Searching for Elements in Package Navigator” on page 53
 “Locating Invoked Services” on page 53
 “Locating Referenced Document Types” on page 54
 “Linking Open Editors” on page 54
Searching for Elements in Package Navigator
To search for elements in Package Navigator
1 In Designer
Search > Integration Server.
2 In Search string, type any portion of the fully qualified name of the element that you
want to find.
3 In the Search on this server only list, select the Integration Server to which you want to
limit the scope of the search.
4 If you want to limit the scope of the search to a specific package, select the package in
the Search in this package only list.
5 Click Search.
Locating Invoked Services
To locate an invoked service
1 In the flow editor, select the INVOKE step containing the service you want to locate.
2 Select Navigate > Show In > Package Navigator. Designer locates and selects the service in

Locating Referenced Document Types
To locate a referenced document type
1 In the editor, select the document reference that you want to locate.
2 Select Navigate > Show In > Package Navigator. Designer locates and selects the IS
document type in the Package Navigator view.
Linking Open Editors
To link open editors
1 On the Package Navigator toolbar, click .
2 In Package Navigator view, select the element whose editor you want to view. If the
element is open, Designer brings its editor to the front.
Filtering Displayed Elements

You can filter the Package Navigator view to display only elements of a specified type.
To filter the displayed elements
1 On the Package Navigator toolbar, click .
2 In the Choose Elements to Display dialog box, do one of the following:
 To display all elements, select Show all elements.
 To display only specific types of elements, select Show selected elements only. Then,
select the elements that you want to display in Package Navigator view.
3 If you want to filter services that Integration Server generates automatically, select the
Hide generated flow services check box.
4 Click OK.

Hiding or Displaying Automatically Generated Flow Services

When you create a step in a process using the Process Development perspective,
Integration Server automatically generates flow services for each step. You can instruct
Designer to hide or display these automatically generated flow services in Package
Navigator view.
To hide or display automatically generated flow services
1 In Designer, click Window > Preferences.

2 In the Preferences dialog box, select Software AG > Service Development > Package
Navigator.
3 To hide flow services automatically generated by Integration Server, select the Hide
generated flow services check box. To show automatically generated flow services, clear
the Hide generated flow services check box.
4 Click OK.
Creating Working Sets

A working set is a subset of elements on one or more Integration Servers. You can create a
working set to limit the contents of Package Navigator to only those elements you want
to see and work with.
To create a working set
1 On the Package Navigator toolbar, click and select Select working set.

2 In the Select Working Set dialog box, click New.
3 Select Integration Server Elements. Click Next.
4 In the Working Set Name field, type a name for the new working set.
5 Under Working Set Content, select the elements to add to the working set. Click Finish.
6 If you want to use the new working set, in the Select Working Set dialog box, select the
working set and click OK. Otherwise, click Cancel.
Caching Elements
You can improve performance in Designer by caching Package Navigator elements that
are frequently used. When elements are located in the Designer cache, Designer does not
need to request them from the Integration Server and can therefore display them more
quickly.

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.
To cache elements

Navigator.
3 In the Number of elements to cache field, type the number of elements that you want to
cache per Designer session. The total number of cached elements includes elements
on all the Integration Servers to which you are connected.
The minimum number of elements is 0. The default is 100 elements. The higher the
number of elements, the more likely an element will be in the cache, which reduces
network traffic and speeds up Designer.
4 Click OK. The caching settings take effect immediately.
Related Topics
 “Clearing the Designer Cache” on page 56
Clearing the Designer Cache

When you clear the Designer cache, you remove Package Navigator view elements from
the 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, a service that has been
stepped into.)
 Unsaved elements.
Keep in mind that the cache is automatically cleared when you close Designer or when
you refresh your connection to Integration Server.
To clear the Designer cache

Navigator.
3 Click Clear Cache. All cached elements are removed from memory.

Note: Clearing cached elements from Designer is different from clearing the contents
of the pipeline from Integration Server cache. If you want to clear the contents of the
pipeline from a server’s cache, see “Configuring a Service’s Use of Cache” on
page 138.
Exporting Elements
Folders or elements in a package, can be exported to your hard drive so that they can be
shared with partners or developers. A folder or element is exported to a ZIP file and
saved on your hard drive. The ZIP file can then be unzipped into the ns directory of a
package on the server. Locking information is not exported.
To export an element or folder
1 In Package Navigator view, select the folder or element that you want to export to
your hard drive.
2 Right‐click the element or folder and click Export from Server.
3 In the Save As dialog box, select the location on your hard drive where you want the
exported element or folder to reside. Click Save.
This exports the element or folder to a ZIP file and saves it on your hard drive. The
ZIP file can then be published on another server.
Note: The Export from Server option is not the same as the File > Export option. With File >

Export, you can export files from the Workbench to the file system.
Related Topics
 “Exporting a Package” on page 119
 “Importing and Overwriting References During Synchronization” on page 293

Viewing an Elements Corresponding Server Files

You can view the names of the server files associated with every Integration Server
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 Package Navigator view, select the elements for which you want to view the
server file names.
2 Right‐click the element and click Lock Properties.
The Lock Contents Results dialog box shows the server files associated with the
element. These server files are system locked (that is, they are not writable on the
server).

3 Assigning and Managing Permissions for Elements
You can limit access to elements to groups of users by 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 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 Integration Server, so that contractors
never see them in Designer.
Related Topics
 “What Is an ACL?” on page 59
 “Assigning ACLs” on page 62
 “Viewing ACL Information for a Server” on page 64
 “How ACLs Affect Other Designer Features” on page 64
 “Troubleshooting ACL Usage” on page 66
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 Designer, Developer, and the Integration Server Administrator.
 Read controls whether a user can view the source code and metadata of an element.
 Write controls whether a user can update an element. This access also controls
whether a user can lock, rename, or delete an element or assign an ACL to it.
 Execute controls whether a user can execute a service.
For more details about these types of access, see the webMethods Integration Server
Administrator’s Guide.

What Happens When a Client Runs a Service with ACLs?

When a client requests that 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, 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 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 “Assigning
ACLs” on page 62.
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. 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, 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, 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, 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), 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” on page 62.
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.
Is ACL Usage Required?

No. However, there are default ACL settings for elements shipped with Integration
Server and default settings for new elements that you create. For details on default ACLs,
see the webMethods Integration Server Administrator’s Guide.
Creating ACLs?
You create ACLs using the Integration Server Administrator. For details, see the
webMethods Integration Server Administrator’s Guide.
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 ACL, Read ACL, Write ACL, or Execute ACL
fields in the Permissions page of the Properties for elementName dialog box.

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),
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 Integration Server.)
Default ACLs and Inheritance

If the element is a top‐level folder, its default ACL is that specified by a configuration file,
not by its parent (the package). If the element is a subfolder, it shares its default ACL
settings with other folders at the same level in the folder hierarchy. For details about
inheritance, as well as the default ACLs that are installed with the webMethods
Integration Server, see the webMethods Integration Server Administrator’s Guide.
Note: An element can inherit access from all elements except a package.
Assigning ACLs
You can assign an ACL to a package, folder, services, and other elements in the Package
Navigator view. Assigning an ACL restricts or allows access to an element for a group of
users.
Keep the following points in mind when assigning ACLs:
 You can assign only one ACL per element.
 You can only assign an ACL to an element for List, Read, or Write access if 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.
 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.
 ACL usage is not required. For more information, see “Is ACL Usage Required?” on
page 61

To assign an ACL to an element
1 Make sure that the ACL you want to assign exists on the Integration Server. If not,
create the ACL in the Integration Server Administrator. For details, see the
webMethods Integration Server Administrator’s Guide.
2 In Package Navigator view, select the package or folder to which you want to assign
an ACL and select File > Properties. In the Properties for elementName dialog box, select
Permissions.
3 On Permissions, select the ACLs that you want to assign for each level of access.
For this
permission... Specify...
List ACL The ACL whose allowed member can see that the element exists

and view the element’s metadata (input, output, etc.).
Read ACL The ACL whose allowed member can view the source code and
metadata of the element.
Write ACL The ACL whose allowed member can lock, check out, edit,
rename, and delete the element.
Execute ACL The ACL whose allowed member can execute the service. This
level of access only applies to services.
4 Under Enforce execute ACL, specify when Integration Server performs ACL checking.

Select one of the following:
Select... To specify that...
When top-level Integration Server performs ACL checking against the service

service only 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 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).
5 Click OK.

Viewing ACL Information for a Server

You can view the users and groups that make up the ACLs on a server.
To view ACL information for an Integration Server
1 In Package Navigator view, select the Integration Server.
2 Click File > Properties.
3 In the Properties for serverName dialog box, select Server ACL Information.
The Server ACL Information page lists the ACLs contained in the Integration Server
to which you are connected. This information is read only; to edit ACLs, users, and
groups, use the Integration Server Administrator.
Related Topics
 “Server ACL Information” on page 323
How ACLs Affect Other Designer Features

 “ACLS and Locking” on page 64
 “ACLs and Running/Debugging Services” on page 65
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 “Guidelines for Locking Java and C/C++ Services” on page 71.
 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 Running/Debugging Services

Keep the following in mind when you run and debug services:
 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 invoked by the top‐level service. If you do not
have access to services invoked by the top‐level service, Designer “steps over” those
services. (Integration Server performs ACL checking for a child service when the
Enforce execute ACL property for the service is set to Always.) Designer executes the
top‐level service and continues to the next flow step. Designer does not step into the
top‐level service.
 To debug a service by sending an XML file to a service, you must have Read access to
the service.
 To set a breakpoint in a service, you must have Read access to the service.
ACLs and Creating, Viewing, and Deleting Elements

Keep the following guidelines in mind when you create, view, or delete elements:
 To create or paste an element, you must have Write access to its parent folder. If you
are not a member of the ACL assigned for Write access to the folder, contact your
server administrator.
 To copy an element, you must have Read access to it and Write access to its parent
folder.
 To rename or delete an element, you must have Write access to it and its parent folder.
 To copy a package, you must be a member of a group assigned to the Replicators
ACL.
 When you create a folder and assign an ACL to it, any elements that you create within
that folder inherit its ACL, until you explicitly set the ACL to something else. For
details about inheritance, see the webMethods Integration Server Administrator’s Guide.
 You may not see all of the elements on the Integration Server in the Package
Navigator view 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 ACL Usage

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 specified in the Properties for elementName
dialog box. If you had previously been able to save the element, the ACL settings may
have changed on the server since you last saved it. For more information, see
“Troubleshooting” on page 76 section in 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, select the Integration Server and click File
> Properties. In the Properties for serverName dialog box, select Server ACL Information.
Integration Server. The Server ACL Information page lists the ACLs contained in the
Integration Server to which you are connected. This information is read only; to edit
ACLs, users, and groups, use the Integration Server Administrator.
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 Package Navigator view. 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
verify, select the element and click File > Properties. Select Permissions in the Properties for
elementName dialog box.
I receive an error when I debug a service.
You must have a minimum of Read access to step through a service. If you don’t have
Read access to the service when you are 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, Designer “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 Package Navigator view” message when I try to find a service in the
Package Navigator view. However, I know it is on the Integration Server.
If you do not see the service listed in the Package Navigator view, 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.


4 Locking and Unlocking Elements
In webMethods Designer, 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 Designer’s Package Navigator view 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.
Local locking on Integration Server is the default locking mode of Designer. If you enable
Designer’s VCS Integration feature, elements are locked and unlocked when you check
them out of or into your version control system repository. 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.
For more information about implementing the VCS Integration feature, see the
webMethods Version Control System Integration Developer’s Guide in the
webMethods_directory\_documentation directory.
Related Topics
 “What Is a Lock?” on page 69
 “Locking Elements” on page 70
 “Viewing the Status of Locked Elements” on page 73
 “Copying, Moving, or Deleting Locked Elements” on page 74
 “Unlocking Elements” on page 74
 “Troubleshooting” on page 76
 “Frequently Asked Questions” on page 78
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.
Elements are shown in the following ways in Designer’s Package Navigator:
Element Status Can I edit? How do I gain rights to edit?

Not locked No Right‐click the element and
then select Lock.
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.
Locking Elements
Before you edit an element, you must lock it. Locking 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.
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.
Related Topics
 “Locking Elements in Designer” on page 70
 “Guidelines for Locking Java and C/C++ Services” on page 71
 “Guidelines for Locking Templates” on page 72
 “System Locking Elements” on page 72
Locking Elements in Designer

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
“Assigning and Managing Permissions for Elements” on page 59.

 When you lock an element, Designer 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. Designer will notify you that these elements cannot be locked and will lock
the rest.
 When you lock an adapter notification, Designer 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.
 When you lock a Java or C/C++ service, Designer locks all other Java or C/C++
services within the folder. This means that other users cannot create Java and C/C++
services in a folder or package that contains the Java or C/C++ services. To create these
services, all existing Java and C/C++ services in the folder must be unlocked and the
user must have Write access to all Java and C/C++ services in the folder. For details,
see “Guidelines for Locking Java and C/C++ Services” on page 71.
 You cannot lock a listener or connection element.
To lock an element
1 In the Package Navigator or in the editor, select the elements that you want to lock.
2 Right‐click the elements and then click Lock.
If the elements were successfully locked, a green check mark appears next to their
icons in Package Navigator view. 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), Designer displays a dialog box listing them. For
information about troubleshooting lock problems, see “Lock and Unlock Problems”
on page 76.
Guidelines for 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.
Guidelines for 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 Properties
command from the right‐click menu. For details, see “Viewing Lock Status of Elements”
on page 73. Usually, a system lock is not reflected in webMethods Designer or the
Integration Server Administrator until you reload the package in which the element
resides.

Important! Before you system lock an element, always verify that it is not locked by a
user on the Integration Server. If an element becomes system locked while a user is
editing it, the user will not know until he or she tries to save changes to the element. If
this occurs, make the element’s corresponding files writable on the server. After this is
done, the user can save his or her changes to the element.
Viewing the Status of Locked Elements

The lock status of an element tells you whether an element is available for locking. If an
element is locked, the lock status tells you who owns the lock and when they locked it.
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, Designer
will not show the system lock status in the Lock Properties dialog box until you
reload the package.
 When another user unlocks an element, you must refresh the Package Navigator 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.
Related Topics
 “Viewing Lock Status of Elements” on page 73
 “Listing All of Your Locked Elements” on page 74
Viewing Lock Status of Elements

You can view the lock status of an element in Package Navigator view.
To view the lock status of an element
 In Package Navigator view, right‐click the element for which you want to view the
status, and then click Lock Properties.
The Lock Contents Results dialog box displays the following information about the
locked element:
 The person who owns the lock on the element.
 The host on which the locked element resides.
 The date the element was locked.
 A list of server‐side files that are part of the element.

Listing All of Your Locked Elements

You can view a list of all the elements that are locked by you in the Package Navigator
view.
To list all of your locked elements
1 In Package Navigator view, select the server for which you want to view your locked
elements.
2 Click File > Properties > Server Locked Elements.
You can unlock individual elements from the Server Locked Elements page 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 74.
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.
Related Topics
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 Designer. If you are an administrator, you can
unlock elements in the Integration Server Administrator as well as in Designer.
Related Topics
 “Unlocking Elements in Designer” on page 75
 “Automatically Unlocking an Element Upon Saving” on page 75

Unlocking Elements in Designer

You must explicitly unlock elements. Disconnecting from the server does not unlock your
element(s), because locks are maintained from session to session.
When unlocking elements, keep the following points in mind:
 Save changes to the elements before you attempt to unlock them.
 When you unlock a single Java or C service, Designer unlocks all other Java or C
services within the folder. For details, see “Guidelines for Locking Java and C/C++
Services” on page 71.
 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, Designer 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 Designer
1 In Package Navigator view, select the elements that you want to unlock.
2 Right‐click the elements and then select Unlock.
3 If the elements you want to unlock contain unsaved changes, Designer 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, Designer 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.
Package Navigator view refreshes and the green check mark next to the element
disappears.
Automatically Unlocking an Element Upon 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 preference must be disabled.

To automatically unlock elements after saving
1 In Designer
2 In the preference navigation tree
Software AG > Service Development > Package Navigator
3 Under Preferences, select the Automatically unlock upon save check box.
4 Click Apply to save your changes. Or click OK to save your changes and close the
Preferences dialog box.
Troubleshooting
This following sections address common problems that may arise when implementing
cooperative development with webMethods components.
Related Topics
 “Lock and Unlock Problems” on page 76
 “Package Management Problems” on page 77
 “Save Problems” on page 77
 “Other Problems” on page 78
Lock and 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 Package Navigator. 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 view.
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 the Package Navigator view.
If it is a Java or C service, reload the package in the Package Navigator view. If it is any
other element, use the Refresh command to refresh the Package Navigator.
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 Packages >Management > Locked 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 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 Package Navigator view simultaneously?
Yes, you can select multiple elements to lock or unlock in the Package Navigator view of
Designer, 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 or
Unlock.
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! It is not recommended that you use locking and unlocking functionality in
an Integration Server cluster. Locking information for elements could be
inadvertently shared with another Integration Server in the cluster. Use a standalone
Integration Server, not a cluster, during development to eliminate these issues.
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 Checking Elements In and Out of a VCS
Designer enables you to create, maintain, and manage custom integration packages for
use by the webMethods Integration Server. Often, many enterprise organizations employ
a version control system (VCS) for the development of software solutions, providing
automatic auditing, versioning, and security to software development projects. Such
products include Microsoft Visual SourceSafe and IBM Rational ClearCase.
With the VCS Integration feature installed in your development environment, you can
check packages or elements in to and out of your version control system (VCS). For
example, to modify a flow service element, you would:
1 Check out the flow service. This automatically checks out its supporting files
(node.ndf and flow.xml).
2 Modify the flow service in Designer and save the changes.
3 Check in the flow service element. This also checks in the node.ndf and flow.xml files
and makes the files read‐only when they are checked in.
Alternatively, if you want to work on other elements in addition to the flow service, you
can check out the entire package.
For information about configuring VCS to work with Integration Server, see the
webMethods Version Control System Integration Developer’s Guide
Related Topics
 “VCS Integration Supported Features” on page 82
 “VCS Integration Unsupported Features” on page 83
 “Locking Locally vs VCS Locking” on page 84
 “System Locking and VCS Integration Feature” on page 85
 “VCS Integration: Basic Concepts” on page 86
 “Adding Packages and Elements to a VCS” on page 91
 “Modifying Elements that are in the VCS” on page 92
 “Reverting Changes to a Checked Out Package or Element” on page 97
 “Getting the Latest Version from the VCS” on page 98
 “Getting an Earlier Version from the VCS” on page 100
 “Deleting Packages and Elements from the VCS” on page 102

 “Restoring Deleted Items” on page 104
 “Copying and Moving Folders or Elements” on page 106
 “Renaming Packages, Folders, and Elements” on page 107
 “Viewing the History of a Folder or Element” on page 108
VCS Integration Supported Features

The use of a shared VCS repository greatly enhances team development of software
solutions. The webMethods Version Control System Integration (VCS Integration) feature
enables you to interact directly with a resident VCS repository in the following ways:
 Check in
 Check out
 Revert changes
 Delete
 Get latest version
 Get earlier version
 View history
The VCS Integration feature also provides the following features:
 Hierarchical behavior — VCS commands applied to packages and folders are applied
to all of the folders and elements they contain.
 Pre‐packaged VCS support for products such as Visual SourceSafe and ClearCase
 Multiple Integration Server support — Multiple Integration Server installations can
interact with a single, shared VCS server, enabling shared development across two or
more servers.
 Multiple user support — Two or more Designer users can interact with the VCS
server while working on the same Integration Server.
 Password‐protected access to the VCS.
 Standard copy and paste, move, and rename behavior —when you use Designer to
apply these actions to any package, folder, or element subject to VCS control, the VCS
Integration feature automatically updates the VCS repository to reflect the changes.
Related Topics

VCS Integration Unsupported Features

The VCS Integration feature is intended for the control of webMethods packages and
their contents in development environments only. The feature does not support:
 The ability to ʺdiffʺ or merge files.
 The ability to move checked out elements loaded from an earlier VCS version.
 Static viewing of previous versions.
 VCS integration of files outside the package namespace structure (that is, components
that do not appear in the Package Navigator view of Designer, or that exist outside
the ..\packages\ns or the ..\packages\code\source directories).
 VCS integration of backup files generated by Designer or Integration Server.
Related Topics

Locking Locally vs VCS Locking

In a shared development environment, there is typically a mechanism for a developer to
lock a file during modification, and to unlock it when the modifications are complete.
This prevents other developers from working on the file at the same time.
Designer and Integration Server provide basic locking and unlocking of project files on
the Integration Server only, with no built‐in interaction with an external VCS. When
locking and unlocking is used, Integration Server files must be checked in to and out of
the VCS manually, outside of the Integration Server or Designer.
The VCS Integration feature extends and is fully compatible with the basic locking
functionality of Integration Server and Designer. When the VCS Integration feature is not
installed or is disabled on an Integration Server, only the basic locking and unlocking
functionality will be available in Designer.
Related Topics
 “Locking and Unlocking Elements” on page 69

System Locking and VCS Integration Feature

Designer and Integration Server support the concept of system locking. When an element’s
server‐side files are marked read‐only on the Integration Server, the element is system
locked. Files are generally system locked when a server administrator accesses the file
through the server’s operating system and marks the files as read‐only. You cannot edit
an element until the server administrator makes the element’s server‐side files writable
and you reload the package in which the element resides.
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 with the
VCS Integration feature. The VCS Integration feature will override any read/write status
changes applied manually by a server administrator.
Related Topics

VCS Integration: Basic Concepts

The VCS Integration feature consists of the WmVCS package and a second package that
is specific to the VCS you are using, as follows:
This package... For this VCS...

WmSourceSafe Visual SourceSafe
WmClearCase ClearCase
You can connect to one VCS repository from each Integration Server.
Designer continues to be fully compatible with Integration Servers that do not have the
VCS Integration feature installed; when Designer connects to an Integration Server
where the VCS Integration feature is not installed, is disabled, or otherwise does not start,
the basic locking functionality remains available in Designer.
To use the VCS Integration feature to check packages and elements in and out of your
VCS repository from Designer, the VCS client software must be installed on the computer
on which Integration Server is running, and must be executable by the user account
under which Integration Server is running. In other words, the VCS Integration feature
does not provide you with a direct connection to your VCS. If you cannot connect to the
VCS through your VCS client software, you will receive an error message each time you
attempt to check packages, folders, or elements in to or out of the VCS from Designer.
Note: You must also have Access Control List (ACL) write privileges on the
Integration Server for the packages, folders, and elements you want to work with.
You can apply the VCS Integration menu commands to Designer folders and elements
that appear in the Package Navigator view of Designer, up to the package level, with the
exception of adapter connections. (For more information on adapter connections, see
“Working with webMethods Adapter Connections” on page 88.)
Components of your webMethods solutions that do not appear in the Package Navigator
view (such as dynamic server pages, HTML documents, templates, and configuration
files) must be manually checked in and out of the VCS repository with your VCS client.
In addition, when you use Designer to apply copy and paste, move, and rename actions
to any package, folder, or element subject to VCS control, the VCS Integration feature
automatically updates the VCS repository to reflect the changes. For example, if you copy
a service from one folder to another, the copied service is automatically added to the VCS
repository in the new location.
Similarly, if you move a folder or element, it will be removed from its original location in
the VCS repository and added to the VCS repository in its new location. Renamed
packages, folders, or elements are also automatically updated in the VCS repository.
Related Topics
 “Hierarchical Operation” on page 87

 “Working with Blaze Rules Services and Web Service Descriptors” on page 87
 “Working with webMethods Adapter Connections” on page 88
 “About Unlocking Elements with Integration Server Administrator” on page 89
 “Working with Java Services” on page 89
 “Checking Elements In and Out of a VCS” on page 81
Hierarchical Operation
The VCS Integration feature works with Designer elements up to and including the
package level. When you apply a VCS Integration command to a container element (a
folder or package), the command is applied to all of the folders and elements in the
container that are subject to VCS management. You can use this feature to check out or
check in elements, or get the latest version or an earlier version of all the elements in an
entire package or folder
For example, if you apply the Check In command to a folder, all supported elements
contained in the hierarchy of that folder are checked in to the VCS.
Note: When you work with a package with many elements, it may take a significant
amount of time to check the package in or out; Designer will not be available during
the check in or check out procedure.
Related Topics
Working with Blaze Rules Services and Web Service Descriptors

When you deploy a rule from Blaze Advisor, a new package, a folder, a subfolder and a
rule node are created in Integration Server. However, only the package is checked in to
the VCS repository, during the rule deployment. You must check in or check out the
folders, subfolders, and rule node manually.
When a Web service descriptor is created in Designer, a WSD node and associated
schemas and document types are created in Integration Server. However, only the WSD
node is checked in to the VCS repository. You must check in or check out the associated
schemas and document types manually.

Related Topics
Working with webMethods Adapter Connections

After they are created, adapter connections appear within a designated package in the
Package Navigator view of Designer. Adapter connections are the one exception to the
rule that all elements shown in the Package Navigator view of Designer are subject to
VCS commands.
Because they are created and maintained in the Integration Server Administrator,
adapter connections cannot be checked in or out of the VCS repository from Designer.
You must create, configure, and modify adapter connections using the Integration Server
Administrator (you must have webMethods administrator privileges to access the
adapter administration screens).
If you want to maintain your adapter connection files in the VCS repository, you must do
so manually with your VCS client.
Note: Because the adapter connection appears within a package, there will be a
corresponding folder created within the VCS repository. However, this folder
contains only the *.ndf file that defines the folder; no adapter connection files are
placed there.
Also note that a publishable document type for an adapter notification cannot be directly
checked in to and out of the VCS repository. It is automatically checked in or out when
you use the VCS client to manually check in or check out its associated adapter
notification.
Related Topics

About Unlocking Elements with Integration Server Administrator

The Integration Server Administrator enables you to unlock server files from the Packages
> Management > Locked Elements page. However, because of architectural considerations,
this unlocking mechanism is not tightly integrated with the VCS Integration feature.
As a result, we strongly recommend that you do not use Integration Server
Administrator to unlock elements that are managed with the VCS Integration feature.
Doing so generally causes the element to enter an ambiguous state within Designer; the
lock status may not be correct, and some VCS Integration feature menu commands may
not be available.
If these conditions occur, refresh the Package Navigator view of Designer. If the
condition persists, apply the Check In command. If you are still having problems, check in
the element with the VCS client and restart the Integration Server.
Related Topics
Working with Java Services

When you copy or move a Java service that is registered in a VCS repository, the service’s
checked in or checked out status in the destination folder is affected according to the
action taken. In addition, certain restrictions apply to the labeling of Java services. For
detailed information, see the following topics:
 “Copying Java Services” on page 90
 “Moving Java Services” on page 90
 “Labeling Java Services in the VCS” on page 91
Related Topics

Copying Java Services

When you copy a Java service, the copied service is added to the VCS repository and
placed in a checked out state in its new folder location, regardless of the check in/check
out status of the source Java service. All other Java services in the destination folder will
be checked out if they are not already checked out.
You cannot copy or move an earlier version of a coded service retrieved from the VCS.
Related Topics
Moving Java Services

The ability to move a Java service is available only with the latest version of a Java
service. If you load an earlier version of a Java service, it cannot be moved.
When you move a Java service, the results are influenced by the state of the Java service
before it is moved (that is, checked in or checked out), and the contents and state of the
destination folder.
 When a checked out Java service is moved, it will always be checked out in the
destination folder. If there are other coded services in the destination folder they too
will be checked out (if they are not already checked out).
 When a checked in Java service is moved to a destination folder that contains no other
checked out coded services, its checked in state will be maintained.
 When a checked in Java service is moved to a destination folder that contains one or
more checked out coded services, its state will change to checked out.
Note: When you move a Java service, its VCS revision history is reset. To retrieve
the earlier information, you must find the previous version of the file as a deleted
item in its previous VCS location and view the revision history there.
Related Topics

Labeling Java Services in the VCS

The VCS Integration feature enables you to get an earlier version of VCS files by
specifying a label, as described in “Getting the Latest Version from the VCS” on page 98.
VCS labels must be created with the VCS client; the VCS Integration feature does not
enable you to create VCS labels from within Designer.
The files supporting a Java service are stored in two locations within the package
directory structure in the VCS repository:
 ..\package\code\source
 ..\package\ns\folderName\JavaServiceNameFolder
The files in these directories must have the same label for the entire Java service to be
retrieved by label.
To minimize any problems, it is recommended that you apply the version label at the
package level, thereby including all folders and elements within the package hierarchy.
Related Topics
Adding Packages and Elements to a VCS

With the VCS Integration enabled, any new packages (or the supported elements within
them) that you create in Designer will be automatically added to the VCS and marked as
checked out.
When you apply a VCS command to a package or element in the Package Navigator view
of Designer, the VCS Integration feature automatically works with the underlying files
that support the package or element. For information on the specific files that are subject
to the VCS Integration feature, see the webMethods Version Control System Integration
Developer’s Guide.
New packages and elements are added to the VCS regardless of how the package or
element was created; it makes no difference if the package or element is created manually
by the user, copied from another package or element, moved, renamed, or created from
an adapter notification or a publishable document type.
Packages and the supported elements within them that were created prior to the
installation of the VCS Integration feature can be added by applying the Check In or
Check Out command, subject to the following behavior:
 When either command is applied to a package or a folder, all of the supported
elements within the container’s hierarchy are added to the VCS.

 When either command is applied to a folder or an element in a folder, the package
and all of the folders in the path to the folder or element will also be added to the
VCS. However, the remaining contents of the package and those higher‐level folders
will not be added to the VCS.
 When a folder containing coded services (Java and C/C++ for example) is added to the
VCS, all of coded services in that folder will be added to the VCS.
 When you apply the Check Out command, the selected item is added to the VCS and
then placed in a checked out state.
Be sure to check in the elements when you have finished working with them; for more
information, see “Checking In Packages and Elements” on page 95. For more information
on which element types are subject to the VCS Integration feature, see the webMethods
Version Control System Integration Developer’s Guide.
Related Topics
Modifying Elements that are in the VCS

When you modify a webMethods solution that you have checked out from the VCS
repository, keep the following points in mind:
 Make sure to check in any elements that you modified with programs other than
Designer (for example, HTML pages and DSPs).

 Make sure to check in any elements (flow services, documents, or other elements in
the Package Navigator view) that you modified with Designer.
If you have previously worked with an earlier version of Designer, you may be
experienced in checking individual files in and out of your VCS (such as flow.xml and
source code files). However, the VCS Integration feature works at the package, folder,
and element level; individual files are checked into and out of your VCS automatically
when you work with the package, folder, or element that contains them:
If you check out … Integration Server checks out these files for you…
A package or a folder  All of the folders and elements within the package or
folder, along with their supporting files.
A service  The node.ndf file for that service
 Other supporting files, depending on the service type,
such as flow.xml and java.frag files
Important! The VCS Integration feature requires that you disable the Automatically
Unlock Upon Save option in Designer, if you have implemented it. For information on
disabling this option, see “Automatically Unlocking an Element Upon Saving” on
page 75.
Related Topics

Checking Out Packages and Elements

Keep the following points in mind when checking out packages and elements from the
VCS.
 The VCS Integration feature does not work with all files in the Integration Server
directory structure. When you check out a package or element from the VCS
repository, you must use the VCS client to manually check out any of its associated
unsupported files that you want to work with, such as:
 IntegrationServer_directory\bin\server.bat (Windows)
 IntegrationServer_directory\bin\server.sh (UNIX)
 IntegrationServer_directory\config\*.cnf
 If your package contains C/C++ or Visual Basic services, you must check out those
services manually with your VCS client and rebuild those services (for example,
recompile the program to generate the DLL).
 Although packages and folders are never shown as checked out in the Package
Navigator view, you can apply the Check Out command to a package or folder to
check out all of the elements within the package or folder.
 When you check out a package or element from ClearCase, the check out is
performed on the branch of the package or element that is currently present in the
underlying view.
 When you check out an individual Java service, all coded services in the folder
containing the Java service are checked out. If, for example, the folder contains three
Java services and a C service, all four services are checked out when you check out
any of the three Java services. When you check in any of the Java services in a folder,
all coded services in the folder are checked in.
 If a package or element does not exist in the VCS, applying the Check Out command
adds the package or element to the VCS repository. For more information about this
behavior, see “Adding Packages and Elements to a VCS” on page 91.
 Although the Check Out command can be applied at the package and folder level, the
check mark is not applied to package and folder icons, only to the checked out
elements within the package or folder.
To check out a package, folder, or element
 In Package Navigator view, right‐click the package, folder, or element you want to
work with and select Check Out.
If a package or folder contains elements that are not supported by the VCS
Integration feature (such as an adapter connection), you will receive a message
naming the elements that will not be checked out. Checking out a package with many
elements might take a significant amount of time. Designer will not be available
during the check out procedure.

After the check out procedure is completed, a small check mark appears to the right
of each checked out element’s icon in the Package Navigator view.
Related Topics
Checking In Packages and Elements

The VCS Integration feature adds packages and elements to your VCS when you apply
the Check In or Check Out command to a file, a folder, or a package.
Keep the following points in mind when checking packages, folders, and elements into a
VCS:
 Because the VCS Integration feature does not work with all files in the Integration
Server directory structure, use the VCS client to manually check in any of the
unsupported files that it uses. For more information, see the webMethods Version
Control System Integration Developer’s Guide.
Navigator view, you can apply the Check In command to a package or folder to check
in all of the elements within the package or folder.
 When you check in a package or element to ClearCase, the check in is performed on
the branch of the package or element that is currently present in the underlying view.

 If a package or element does not exist in the VCS, applying the Check In command
adds the package or element to the VCS repository. For more information about this
behavior, see “Adding Packages and Elements to a VCS” on page 91.
 If a package or element has unsaved changes applied to it, you must save the changes
to the package or element before you can check it in.
To check in a package, folder, or element
1 In Package Navigator view, right‐click the package, folder, or element that you want
to check in, and select Check In.
2 In the Comment for Check In dialog box, enter a comment that describes the changes
made to the package or element. This comment will be displayed in the revision
history for the element. If you do not enter a comment, the revision history will
display only user, time, and date information for this check in.
3 Click OK. The small check mark is removed from the right of the package or element’s
icon in the Package Navigator view.
Notes:
 If the version of the file you checked out is not the same as the one that is currently
available, another user has checked in the file in between. Your check in will not be
done and an error message will be displayed.
 If you check in a package that existed before VCS Integration, the manifest.v3 file will
not get checked into the VCS.
 If you have made no changes to the package, folder, or element, the comment you
enter will be ignored by Visual SourceSafe unless you configure Visual SourceSafe to
check in unchanged files.
 Checking in a package with many elements might take a significant amount of time.
Designer will not be available during the check in procedure.
Related Topics

Reverting Changes to a Checked Out Package or Element

There may be times when you want to discard the changes made to a checked out
package or element and return the package or element to its original version. This is
commonly done when testing potential changes to files in the VCS repository.
The Revert Changes command discards all changes made to a package or element and
replaces the Integration Server instance of the package or element with the most recent
version checked into the VCS repository. This provides you with a sandbox feature for
testing proposed changes. Only packages or elements that are checked out can be
reverted.
Keep the following points in mind before reverting changes to a checked out package,
folder, or element:
 Access Control List (ACL) permission settings are not revertible. If you make changes
to ACL permissions for an element, and then revert the element, the ACL permissions
will remain unchanged.
 You can use the Revert Changes command to reverse a check out command that you
applied by mistake, even if no changes are made to the file.
 Although folders are never shown as checked out in the Package Navigator view, you
can apply the Revert Changes command to a folder to revert changes to all of the
elements in the folder’s hierarchy.
 Reverting changes to a newly created element (prior to initial check in) may cause the
element to be corrupted. It is recommended that you check in a new element
immediately after creation and then check it out again before you enter any
modifications.
 When you apply the Revert Changes command to a package, or to a folder in a
package, all of the supported elements within the container’s hierarchy that are
currently checked out are reverted.
 The Revert Changes command reloads the entire package containing the element; this
may cause sessions currently using services in the package to fail.

To revert changes to a checked out package, folder, or element
1 In Package Navigator view, right‐click the package, folder, or element for which you
want to revert changes, and select VCS > Revert Changes.
2 In the Revert Node alert window, click OK to confirm reverting the element to the
most recent version in the VCS repository.
The small check mark is removed from the right of the element’s icon in the Package
Navigator view, the checked out files are replaced with the most recent version
checked in to the VCS repository, and the entire package is reloaded.
Related Topics
Getting the Latest Version from the VCS

The VCS Integration feature provides the Get Latest Version command to replace packages,
folders, and elements on Integration Server with the most recent version in the VCS
repository (referred to as a sync operation in some VCS programs).

Keep the following points in mind when retrieving the latest version of a package, folder,
or element from a VCS repository.
 You cannot apply the Get Latest Version command to checked out packages, folders, or
elements. You cannot apply the command to a package or a folder if any of the
supported elements within the container’s hierarchy are checked out.
Navigator view, you can apply the Get Latest Version command to a package or folder
to get the latest version of all of the elements within the package or folder.
 For ClearCase, the Get Latest Version command updates the package, folder, or
element in the branch configured for the view. Do not use the Get Latest Version
command for Dynamic Views because Dynamic Views always contain the latest
version.
 Some folders or elements might be deleted after you apply the Get Latest Version
command. This will occur when there is no current version of that folder or element
(that is, it has been deleted from the VCS repository since the last update).
 The Get Latest Version command reloads the entire package containing the element.
This might cause sessions currently using services in the package to fail.
To get the latest version of package, folder, or element
 In Package Navigator view, right‐click the package, folder, or element for which you
want to retrieve the latest version, and select VCS > Get Latest Version.
Note: If a folder contains locked non‐Java elements and you apply the Get Latest Version

command to an unlocked Java element in that folder, the error message “Subnode(s)
checked out” displays. Check in all elements in the folder and try again.
Related Topics

Getting an Earlier Version from the VCS

The VCS Integration feature provides the Get Earlier Version command to replace
packages, folders, and elements on the Integration Server with an earlier version in the
VCS repository.
Keep the following points in mind when retrieving an earlier version of a package, folder,
or element:
 To retrieve an earlier version, you must know the date or VCS label of the earlier
version. You can obtain this information with the View History command. (For more
information, see “Viewing the History of a Folder or Element” on page 108.)
The VCS Integration feature does not provide the ability to assign VCS labels; you
must use your VCS client to assign a label if one does not exist. To eliminate any
problems, it is recommended that you apply the version label at the package level,
thereby including all folders and elements within the package hierarchy.
 You cannot apply the Get Earlier Version command to checked out packages, folders, or
elements.
 You cannot apply the command to a package or a folder if any of the supported
elements within the container’s hierarchy is checked out.
 Most VCS servers will not permit you to copy, move, delete, or rename earlier
versions of elements. It is recommended that you not apply any of these actions to an
earlier version file, as unpredictable results might occur.
Navigator view, you can apply the Get Earlier Version command to a package or folder
to get an earlier version of all of the elements within the package or folder.
 For ClearCase, the Get Earlier Version command loads the version of the branch
indicated by the ClearCase Branch Name field in Integration Server Administrator (see
webMethods Version Control System Integration Developer’s Guide). If no branch is
identified in that field, ClearCase loads the main ClearCase branch. Do not use the Get
Earlier Version command for Dynamic Views because Dynamic Views always contain
the latest version.
 Some folders or elements might be deleted after you apply the Get Earlier Version
command. This will occur when there is no earlier version of that folder or element
(that is, it has been added to the VCS repository since the creation of the version being
retrieved).

 When you apply the Get Earlier Version command to a Java service, the earlier version

will be loaded for all Java services in that folder, as well as for all folders and elements
contained in the folder.
 The Get Earlier Version command also reloads the entire package containing the
element. This might cause sessions currently using services in the package to fail.
To get an earlier version of a package, folder, or element
1 In Package Navigator view, right‐click the package, folder, or element for which you
want to retrieve the latest version, and select VCS > Get Earlier Version.
2 In the Get Earlier Version dialog box, do one of the following:
Select... To...
Date Retrieve an earlier version using the date (Visual SourceSafe).
In the field next to Date, enter the VCS repository date and time
of the version you want to retrieve.
You must type the date and time using the Designer format
MM/DD/YY HH:MM:SS, where HH:MM:SS is in 24‐hour time
format. For example, in the History dialog box, the VCS time is
presented in the format:
User: UserName Date: 1/13/06 Time: 2:56p
This signifies January 13, 2006, 14:56 hours. You must type the
date into the Date field in this format:
01/13/06 14:56
Do not include the time zone (for example, EST) when typing
the date and time. The precision of the specified time (that is,
whether minutes and seconds are accepted, or minutes only) is
determined by the time format of the VCS application. For
example, Visual SourceSafe dates files with minutes only.
Label Get an earlier version by providing the VCS label (Visual
SourceSafe and ClearCase) or to get an earlier version by
providing a version number (ClearCase).
In the field next to Label, enter the VCS label text or version
number.
3 Click OK. All supported and checked in elements are updated to the specified version
in the VCS repository.
Note: If a folder contains locked elements that are not Java services and you apply
the Get Earlier Version command to an unlocked Java service in that folder, the error
message “Subindex() checked out” displays. Check in all elements in the folder
and try again.

Related Topics
Deleting Packages and Elements from the VCS

The VCS Integration feature enhances the existing Delete command to delete packages,
folders, and elements from both Integration Server and the VCS repository.
Keep the following points in mind when deleting items from an Integration Server on
which the VCS Integration feature is configured:
 The Delete command can be applied to packages, folders, and elements regardless of
the checked in/checked out status of the elements.
 You cannot delete packages or elements checked out by other users.
 When the Delete command is applied to a package, Integration Server saves a copy of
the package in the package recovery area of Integration Server.
 When the Delete command is applied to a folder or element in a folder (a service, for
example), the folder or element is deleted completely from the Integration Server. For
those VCS servers that support restorable deletion, the element is deleted from the
repository view but not destroyed.
 When you apply the Delete command to a package, or to a folder in a package, all of
the elements within the container’s hierarchy (both VCS elements and non‐VCS
elements) are deleted.

 For ClearCase, the Delete command removes the package, folder, or element from the
versioned object base (VOB), so that the package, folder, or element is removed from
all branches.
 Visual SourceSafe and ClearCase do not support entry of a delete comment. The VCS
history will show only the VCS user name and the time of deletion.
Note: Do not apply the Delete command to any earlier version packages or elements
that are checked out, as unpredictable results may occur.
To delete a package, folder, or element from both Integration Server and the VCS
1 In Package Navigator view, select the package, folder, or element you want to delete.
2 Select Edit > Delete. Do one of the following:
The Delete Confirmation dialog box appears. If you are deleting a publishable
document type, Designer prompts you to delete the associated Broker document type
as well. For more information about deleting Broker document types, see “Deleting
Elements” on page 46.
3 Click OK.
If a VCS package or element is checked out by another user, the package or element
will not be deleted, and an error message appears. In addition, any parent folders
leading to the checked out element will not be deleted.
When deleting a package, a message box appears stating that the deletion is complete
and that the deleted package has been copied to the recovery area of the Integration
Server. If this message appears, click OK.
Related Topics
 “Deleting Publishable Document Types” on page 286
Related Topics

Restoring Deleted Items

After you delete a package, folder, or element from both Integration Server and the VCS
repository, you may want to restore the package, folder, or element back into the
Integration Server from the VCS server.
Related Topics
 “Restoring a Deleted Package” on page 104
 “Restoring a Deleted Folder or Element” on page 105
Restoring a Deleted Package

Packages are best restored with the Recover Packages feature of the Integration Server
Administrator (only administrator users can recover a package). After the package is
recovered in Integration Server, refresh the Package Navigator view to display the
recovered package, and apply the Check In command to the package to add it to the VCS
repository.
Related Topics
 “Restoring a Deleted Folder or Element” on page 105

Restoring a Deleted Folder or Element

You can restore a deleted folder or element (a service, for example) in the VCS repository
if you did not subsequently delete it completely from the VCS repository
To restore a folder or element that has been deleted from both Integration Server and the VCS
1 With your VCS client, restore the folder or element in the VCS repository.
Important! If the folder or element contains subfolders or individual files, be sure
you restore all of the folder or element contents, typically by applying a recursive
restore. If you restore a service, for example, without restoring its node.ndf file,
the service will not be recognized by Integration Server.
2 Using the VCS client, check out the restored element to its original location in the
..\packages\ns directory. You may receive a message that the folder or element does
not exist, with a request to create the folder or element. If so, respond so that all
folders, elements, and files are created.
3 In Package Navigator, right‐click the package that contained the deleted element and
select Reload Package. This displays the restored element in the Package Navigator
view.
Note: At this point, although the restored element is in a checked out state on the
VCS server, it does not display the checked out symbol in the Package Navigator
view.
4 In Package Navigator view, right‐click the restored element and select Check In.
Related Topics
 “Restoring a Deleted Package” on page 104

Copying and Moving Folders or Elements

The VCS Integration feature integrates with the copy, paste, and move functionality of
Designer. The results of all these actions are applied to the VCS repository. You cannot
copy and paste, move an earlier version of a package, folder, or element.
Important! When you move or rename a folder or element, you are effectively creating
a new entity in the VCS repository. Therefore, the previous folder or element is
deleted and a new entity is created. This means that a new revision history is started
for the moved or renamed entity as well. If you want to view previous revision
information for a moved or renamed folder, or element, you must locate the deleted
version of the file in the VCS repository and view the revision history there.
Because the default behavior of the VCS Integration feature is to add any new folder or
element to the VCS repository, a copied or moved folder or element automatically
appears in the VCS repository in its new location. In the case of a moved item, the
previous location is deleted from both Designer and the VCS repository.
A copied folder or element is always placed in a checked out state in its new location. A
moved folder or element retains its checked in or checked out state; special conditions
apply when you copy or move a coded service. For more information on copying and
moving coded services, see “Working with Java Services” on page 89.
When you move an element that has dependents, the dependents will not be updated
until you check in the moved element. This may cause failure of any services that use the
dependent elements.
Related Topics

Renaming Packages, Folders, and Elements

The VCS Integration feature integrates with the rename functionality of Designer. The
results of all these actions are applied to the VCS repository. You cannot rename an
earlier version of a package, folder, or element.
When you rename a package, folder, or element, the renamed item retains its checked in
or checked out state, and the new name is applied in the VCS repository. Also, note that
when you rename an element that has dependents, the dependents will not be updated
until you check in the renamed element. This may cause failure of any services that use
the dependent elements.
Related Topics

Viewing the History of a Folder or Element

The VCS Integration feature provides the View History command to display the revision
history of a selected folder or element. The View History command is not available at the
package level.
 If the folder or element exists in the VCS repository, the lock status and VCS revision
history is displayed.
 If the folder or element is not contained in the VCS repository (that is, it exists only on
Integration Server), only the lock status of the element is displayed.
 If a selected element contains more than one file (for example, a flow.xml file and
node.ndf file in a flow service), the VCS revision history presents information for each
file.
 For ClearCase, the View History command displays the history of the folder or element
in all branches that contain the file.
Note: Technically, folders are not checked in or checked out of the VCS repository; it is
actually the elements within the folder that are checked in or out. When viewing the
history for a folder, you are actually viewing the history of the node.idf file within the
folder.
The following information is available for files supporting folders and elements in the
VCS repository:
Information Definition
User The VCS user account name under which the revision was executed.
Date The date applied to the revision by the VCS server.
Time The time applied to the revision by the VCS server.
Checked In The full VCS project path for the checked in file.
Comment Text entered by the user at check in time. This may contain no text if
the user did not enter a comment.
dev_user The Designer user under which the revision was executed.
is_host The name of the host on which Integration Server is running.
dev_host The name of the host on which Designer is running.
is_time The date and time applied to the revision by Integration Server.
Label The VCS label applied to the file. If no VCS label exists, this entry is
not displayed.
Label Comment Text entered by the user when the label was applied. This may
contain no text if the user did not enter a comment.

When you move or rename a folder or element, the previous folder or element is deleted
and a new entity is created. This means that a new revision history is started for the
moved or renamed entity as well. If you want to view previous revision information for a
moved or renamed folder, or element, you must locate the deleted version of the file in
the VCS repository and view the revision history there.
To view the history of an element
1 In Package Navigator view, right‐click the element for which you want to view
history and select View History.
The elmentName History dialog box appears. If necessary, you can copy text from the
dialog box and paste it into another program.
2 When you have finished viewing the history information, click OK.
Related Topics


6 Managing Packages
6 Managing Packages
A package is a container that is used to bundle services and related elements, such as
specifications, IS document types, IS schemas, and triggers. When you create a folder,
service, IS document type, or any element, 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.
Related Topics
 “Creating a Package” on page 111
 “Documenting a Package” on page 113
 “Viewing Package Settings, Version Number, and Patch History” on page 114
 “Assigning a Version Number to a Package” on page 115
 “Copying Packages Between Servers” on page 116
 “Reloading a Package” on page 118
 “Deleting a Package” on page 118
“Exporting a Package” on page 119
 “About Package Dependencies” on page 119
 “Assigning Startup, Shutdown, and Replication Services to a Package” on page 122
Creating a Package
When you want to create a new grouping for services and related files, create a package.
When you create a package, Designer creates a new subdirectory for the package in the
file system on the machine where the Integration Server is installed. For information
about the subdirectory and its contents, see the webMethods Integration Server

6 Managing Packages
Related Topics
 “Guidelines for Naming Packages” on page 112
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”. Designer uses the “Wm” prefix for predefined
packages that contain services, IS document types, and other files.
 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.
Related Topics
Creating a Package
To create a package
1 In Designer
File > New > Package
2 In New Integration Server Package dialog box, select the Integration Server on which
you want to create the package.
3 In the Name field, type the name for the new package using any combination of letters,
numbers, and the underscore character. For more information, see “Guidelines for
Naming Packages” on page 112.

6 Managing Packages
4 Click Finish. Designer refreshes the Package Navigator view and displays the new
package.
Related Topics
 “Guidelines for Naming Packages” on page 112
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.
Related Topics
 “Accessing Package Documentation” on page 114

6 Managing Packages
Accessing Package Documentation
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 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, Integration Server automatically
displays the index.html file.
Related Topics
 “Documenting a Package” on page 113
Viewing Package Settings, Version Number, and Patch

History
For each package, Designer tracks and displays settings, version number, and a history of
installed patches. A patch is a partial upgrade, change, or fix to the contents of a package.
You might want to check the settings or patch history of a package for the following
reasons:
 To determine which version of the package is installed.
 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 Global Support which versions of predefined packages are
installed on your Integration Server.

6 Managing Packages
To view package settings, version number, and patch history
1 In Package Navigator view, select the package whose properties you wish to view.
3 In Properties for PackageName dialog box, select Package Settings.
The Package Settings page displays the version and patch history for the package since
the last full release of the package. (A full release of a package incorporates all
previous patches for the package.) For more information about package settings, see
“Package Properties” on page 325.
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.
Related Topics
 “Package Properties” on page 325
 “Assigning a Version Number to a Package” on page 115
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.
Keep the following in mind when assigning version numbers to packages:
 By default, Designer assigns the version number 1.0 to each package that you create.
 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.
 Assign and change package version numbers through Designer 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 Integration Server.

6 Managing Packages
To assign a version number to a package
1 In Package Navigator view, select the package to which you want to assign a version
number.
3 In Properties for PackageName dialog box, select Package Settings.
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 Click OK.
Related Topics
Copying Packages Between Servers

You can copy a package to another Integration Server in one of two ways:
 From Designer. You can copy a package and its contents to another Integration Server
from within Designer by performing a copy or a drag‐and‐drop action. Copying
packages using either of these methods provides a quick way to share a set of services
and their supporting files with other developers in a development environment.
 From Integration Server Administrator. You can also copy a package from within the
Integration Server Administrator by replicating the package. You can then send, or
publish, the package to other Integration Servers. Copying packages using this
method allows you to customize the way in which packages are replicated and
published. This method is useful for managing releases between development and
production environments, for deploying releases to partners or customers, or for
distributing package updates to developers working in large, collaborative
environments.
For information about replicating packages and managing releases from within
Integration Server Administrator, see the webMethods Integration Server Administrator’s
Guide.
Related Topics
 “Copying Packages” on page 117

6 Managing Packages
Copying Packages
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.
To copy a package between servers
1 In Package Navigator view, select the package you want to copy.
2 Click Edit > Copy.
3 If the package you want to copy contains elements with unsaved changes, Designer
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 Click Edit > Paste.
Related Topics
 “Copying Packages Between Servers” on page 116

6 Managing Packages
Reloading a Package
Sometimes, you need to reload a package on the server to activate changes that have been
made to it outside of 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 Package Navigator view.
When you refresh the Package Navigator view, Designer retrieves a fresh copy of the
contents of all the packages from the memory of the Integration Server. When you
reload a package, 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 Package Navigator view, select the package you want to reload.
2 Right‐click the package and 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 Package
Navigator view.
When you delete a package from Designer, Integration Server saves a copy of the
package. If you later want to recover the package and its contents, contact your server
administrator. Only Integration Server Administrator users can recover a package. For
more information about recovering packages, see the webMethods Integration Server
Before you delete a package, make sure that:
 Other users or other services do not use (depend on) the services, templates, IS
document types, and schemas in the package. You can use the Package Dependencies
option to identify other services that are dependent on a service in a package that you
want to delete. For more information, see “Identifying Package Dependencies” on
page 120.
 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.

6 Managing Packages
To delete a package
1 In Package Navigator view, select the package you want to delete.
2 Click Edit > Delete.
Related Topics
 “Identifying Package Dependencies” on page 120
Exporting a Package
Packages 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 Package Navigator view, select the package you want to export to your hard drive.
2 Right‐click the package and click Export from Server.
3 In the Save As dialog box, 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.
Note: The Export from Server option is not the same as the File > Export option. With File >

Export, you can export files from the Workbench to the file system.
Related Topics
 “Exporting Elements” on page 57
About Package Dependencies

If a package needs the services in another package to load before it can load, you must set
up package dependencies. For example, you should identify package dependencies if a
startup service for a package invokes a service in another package. The startup service
cannot execute if the package containing the invoked service has not yet loaded.
You should also identify package dependencies if Java services in a package need to
access Java classes contained in another package.

6 Managing Packages
Important! Other webMethods components might include packages that register new
types of elements in Designer. 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 Designer can recognize instances
of the new element type. For example, if you create new flat file schemas, you should
save the flat file schemas in packages that identify the WmFlatFile package as a
package dependency.
Related Topics
 “Removing Package Dependencies” on page 121
 “Viewing Package Settings, Version Number, and Patch History” on page 114
Identifying Package Dependencies

Keep the following in mind when creating package dependencies:
 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.
 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.
 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.
 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,
Integration Server does not load the dependent package. Integration Server writes a
dependency load error for the dependent package to the server log.
To identify a package dependency
1 In Package Navigator view, select the package for which you want to specify package
dependencies.
3 In Properties for PackageName dialog box, select Package Dependencies.

6 Managing Packages
4 Click .
5 In the Add Dependent Package dialog box, enter the following information:
‘In this field... Enter...
Package The name of the package you want Integration Server to load
prior to loading the package selected in the Package Navigator
view. Type the name of the package in the Package field or click
Browse to choose the dependent package.
Version The version number of the package you specified in the Package
field.
More than one version of the same package might contain the
services and elements that a dependent package needs
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 Click OK in the Properties for PackageName dialog box.
Related Topics
 “Removing Package Dependencies” on page 121
Removing Package Dependencies

Use the following procedure to remove a package dependency that is no longer needed.
For example, 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 Package Navigator view, select the package for which you want to remove a
package dependency.

6 Managing Packages
3 In Properties for PackageName dialog box, select Package Dependencies.
4 Select the package dependency you want to remove and click .
5 Click Yes to confirm the deletion.
6 Click OK in the Properties for PackageName dialog box.
Related Topics
Assigning Startup, Shutdown, and Replication Services to a

Package
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.
Related Topics
 “What Is a Startup Service?” on page 122
 “What Is a Shut Down Service?” on page 124
 “What Is a Replication Service?” on page 125
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 Designer or the Integration Server Administrator to reload a
package.
 When someone uses Designer 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.
Related Topics
 “Assigning a Startup Service” on page 123
 “Removing a Startup Service” on page 124

6 Managing Packages
Assigning a Startup Service

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.
 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.
 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.
To assign a startup service
1 In Package Navigator view, select the package to which you want to assign startup
services.
3 In Properties for PackageName dialog box, select Startup/Shutdown Services.
4 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 Click OK.
Related Topics
 “Removing a Startup Service” on page 124

6 Managing Packages
Removing a Startup Service

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 a startup service
1 In Package Navigator view, select the package for which you want to remove startup
services.
4 Under Startup services, select the service you want to remove from Selected services list,
and click .
5 Click OK.
Related Topics
 “Assigning a Startup Service” on page 123
What Is a Shut Down 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.
Related Topics
 “Assigning a Shutdown Service” on page 124
 “Removing a Shutdown Service” on page 125
Assigning a Shutdown Service

When you assign a shutdown service to a package, you can only assign a service that
resides in the same package. For example, a shutdown service for the “Finance” package
must be located in the “Finance” package.

6 Managing Packages
To assign a shutdown service
1 In the Package Navigator view, select the package to which you want to assign
shutdown services.
4 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.
Related Topics
 “Removing a Shutdown Service” on page 125
Removing a Shutdown Service
To remove a shutdown service
1 In Package Navigator view, select the package for which you want to remove
shutdown services.
4 To remove a shutdown service, under Shutdown services, select the service you want to
remove from Selected services list, and click .
5 Click OK.
Related Topics
 “Assigning a Shutdown Service” on page 124
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.

6 Managing Packages
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).
Related Topics
 “Assigning a Replication Service” on page 126
 “Removing a Replication Service” on page 126
Assigning a Replication Service

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.
To assign a replication service
1 In the Package Navigator view, select the package to which you want to assign
3 In Properties for PackageName dialog box, select Replication Services.
4 Click .
5 In the Select a replication service dialog box, select the service that you want to use as
a replication service.
6 Click OK.
Repeat these steps for each service you want to add as a replication service.
Related Topics
 “Removing a Replication Service” on page 126
Removing a Replication Service
To remove a replication service
1 In the Package Navigator view, select the package for which you want to remove

6 Managing Packages
3 In Properties for PackageName dialog box, select Replication Services.
4 Select the replication service you want to remove and click .
5 Click Yes to confirm the deletion.
6 Click OK.
Related Topics
 “Assigning a Replication Service” on page 126

6 Managing Packages

7 Building Services
Services are method‐like units of logic that operate on documents. They are executed by
Integration Server. You build services to carry out work such as extracting data from
documents, interacting with back‐end resources (for example, submitting a query to a
database or executing a transaction on a mainframe computer), and publishing
documents to the Broker. Integration Server is installed with an extensive library of built‐
in services for performing common integration tasks. Adapters and other add‐on
packages provide additional services that you use to interact with specific resources or
applications. webMethods graphical implementation language, flow, enables you to
quickly aggregate services into powerful sequences called flow services.
Related Topics
 “A Process Overview” on page 129
 “Package and Folder Requirements” on page 130
 “Declaring a Service Signature” on page 130
 “Specifying Run‐Time Parameters” on page 136
 “Configuring Services to Retry” on page 142
 “Configuring Service Auditing” on page 145
 “Assigning a Universal Name to a Service or Document Type” on page 149
 “Assigning an Output Template to a Service” on page 153
A Process Overview
Building a 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 debugging. For information about this
stage, see “Creating a New Flow Service” on page 160.
Stage 2 Adding logic to the new service. During this stage, you specify the work that
you want the service to perform. If you are building a flow service, you
add logic by inserting flow steps into the service. For information about
this stage, see “Building Flow Services” on page 155.
Stage 3 Declaring the service signature. During this stage, you define the service’s
inputs and outputs. For information about this stage, see “Declaring a
Service Signature” on page 130.

7 Building Services
Stage 4 Mapping pipeline data. If you are building a flow service, during this stage,

you route input and output variables between services that are invoked in
the flow. For information about this stage, see “Mapping Data in Flow
Services” on page 193.
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 136.
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 153 or refer to
the Dynamic Server Pages and Output Templates Developer’s Guide.
Stage 7 Debugging. During this stage you can use the tools provided by Developer
to run and debug your flow service. For information about this stage, see
“Running and Debugging Flow Services” on page 229.
Package and Folder Requirements

Before you create a new service, you must:
 Make sure the package in which you want to create the service already exists. If the package
does not already exist, create it using Designer. For more information about creating a
package, see “Creating a Package” on page 111.
 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 Designer. For
information about creating folders, see “Creating New Elements” on page 34. For
information about ACL permissions, see “Assigning and Managing Permissions for
Elements” on page 59.
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 34.
Declaring a Service Signature

Input and output parameters are the names and types of fields that the service requires 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 a signature for all types of services: flow services, Java services, and services
written in other supported programming languages.
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:

7 Building Services
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
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 Designer. Without
declared input and output parameters, you cannot:
 Link data to and/or from the service using the Pipeline view.
 Assign default input values to the service on the Pipeline view.
 Validate the input and output values of the service at run time.
 Run or debug the service in Designer 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, it is strongly recommended that you make it a practice to declare a
signature for every service that you create.
Designer supports several data types for use in services. Each data type supported by
Designer 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.
Related Topics
 “Specifying Input Parameters” on page 132
 “Specifying Output Parameters” on page 133
 “Declaring Input and Output Parameters” on page 133
 “Running and Debugging Flow Services” on page 229

7 Building Services
Specifying Input Parameters

When you define the input parameters for a service, keep the following points in mind:
 Specify all inputs that a calling program must supply to this 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 view to manually link
them to one another.
 Avoid using multiple inputs that have the same name. Although Designer 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
Designer, see “Data Types” on page 385.
 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.
 Trigger services have specific input parameter requirements. If you intend to use a 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 the webMethods Integration Server JMS
Client Developer’s Guide.

7 Building Services
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 Designer, select the service
and then click the Reset button next to Reset Cache in the Properties view. 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 Output Parameters

On the output side of the Input/Output tab you specify the variables that you want the
service 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 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 view to manually link
them to one another.
 Avoid using multiple outputs that have the same name. Although Designer 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 service. 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 “Data Types” on page 385.
 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.
Declaring Input and Output Parameters

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.

7 Building Services
Input/Output tab
Define the service’s

input parameters ...and output
on this side... 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 declare a service signature in one of 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.
 Manually insert input and output variables. Drag variables from the Palette view to the
Input or Output sides of the Input/Output tab.
Related Topics
 “Using a Specification as a Service Signature” on page 134
 “Using an IS Document Type to Specify Service Input or Output Parameters” on
page 135
 “Inserting Input and Output Parameters” on page 136
Using a Specification as a Service Signature

You can use a specification as the service signature. A specification is a “free‐standing” IS
element that defines a set of service inputs and outputs.
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. (Designer displays the parameters, but does

7 Building Services
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.
To assign a specification to a service
1 In the Package Navigator view, open the service to which you want to assign a
specification.
2 Click the Input/Output tab.
3 In Specification Reference, type the fully qualified name of the specification, or click
to select it from a list.
4 Click Okay.
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.
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.
To use an IS document type as service input or output parameters
1 In the Package Navigator, double‐click the service to which you want to assign the IS
document type.
3 In the Input or Output box, 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
Package Navigator to the box below the Validate input or Validate output check boxes
on the Input/Output tab.
4 Click File > Save.

7 Building Services
Inserting Input and Output Parameters

You can define a service signature by dragging variables from the Palette view to the
Input or Output side of the Input/Output tab.
To declare input and output parameters for a service
1 In the Package Navigator view, open the service for which you want to declare input
and output parameters.
3 If the Palette view is not visible, display it by clicking .
4 In the Palette view, select the type of variable you want to define and drag it to the
Input or Output side of the Input/Output tab.
5 Type a name for the variable and press ENTER.
6 With the variable selected, set variable properties and apply constraints using the
Properties view.
7 If the variable is a document or document list, repeat steps 4–6 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.
Note: You can add a document reference to a service signature by selecting an IS
document type in the Package Navigator view and dragging it to the
Input/Output tab.
Specifying Run-Time Parameters

As a developer of a service, you can use the Properties view 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 Designer.
For details, see “Caching Elements” on page 55.
 Execution locale of a service. You can set the type of locale in which the Integration
Server executes at run time.
Important! The run‐time parameters 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.

7 Building Services
Related Topics
 “Maintaining the State of Service” on page 137
 “Configuring a Service’s Use of Cache” on page 138
 “Specifying the Execution Locale” on page 141
Maintaining the State of Service

When a remote client opens a session on a webMethods Integration Server, the server
automatically builds a session object for that client. The server uses this object to maintain
specific information about the client requesting the service, such as user name and
password. The server maintains the session object for the duration of the session (that is,
until the client program explicitly closes the session on the server or the session times out
due to client inactivity).
When you develop services in a language such as Java, C/C++, or Visual Basic, you can
use the “put” method to write information to the session object. You might do this to
store information that a sequence of services needs to maintain a connection to an
external system.
A service that is an atomic unit of work (that is, one that is wholly self contained and not
part of a multi‐service transaction to an external system) does not to need to have its
session object maintained when it is finished executing. For performance reasons, you
may want to configure these types of services to run in “stateless” mode. Services that
run in “stateless” mode use fewer resources and do not consume a licensed seat on
webMethods Integration Server.
Related Topics
 “Specifying the Run‐Time State for a Service” on page 137
Specifying the Run-Time State for a Service

Configure a service’s run‐time state in the Properties view.
To configure a service’s run-time state
1 In the Package Navigator, open the service that you want to configure.
2 In the Run time category of the Properties view, 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.

7 Building Services
 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.
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 Run time category to False.
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.
Related Topics
 “Types of Services to Cache” on page 138
 “Controlling a Service’s Use of Cache” on page 139
 “Specifying the Duration of Cached Results” on page 140
 “Using the Prefetch Option” on page 140
 “Configuring Caching of Service Results” on page 141
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. Following are guidelines for you to consider when determining
whether to cache the results for a service.
 “Services Suited for Caching” on page 139
 “Services that You Should Not Cache” on page 139

7 Building Services
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 in the Properties view 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 Integration Server, work
with your server administrator to monitor and evaluate your service’s use of cache.

7 Building Services
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 Designer, select the service
and then click Reset next to Reset Cache in the Properties view. 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 Cached Results

Integration Server maintains results in cache for the period of time you specify in the
Cache expire property on the Properties view. 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 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.
Keep the following points in mind when using Prefetch:
 Use Prefetch carefully. Overuse can quickly exhaust the memory available for cache.
 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.
 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 Integration
Server.

7 Building Services
Configuring Caching of Service Results

Configure cache settings for a service in the Properties view.
To enable caching of pipeline contents after a service is invoked
1 In the Package Navigator, open the service for which you want to configure caching.
2 In the Run time category of the Properties view, set Cache results to True.
3 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.
4 If you want to use prefetch, set Prefetch to True, and then 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
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 configure Integration Server to recognize custom locales. By default, the
service uses the null locale. That is, it uses no locale policy.

7 Building Services
To specify the execution locale of a service
1 In the Package Navigator, open the service that you want to configure.
2 In the Run time category of the Properties view, 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.
3 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.
4 Click OK. Integration Server will execute the service in the specified locale.
Configuring Services to 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 Integration Server waits a short interval of time and then retries the service.

7 Building Services
To configure a service to retry, you specify the maximum retry attempts and the retry
interval. The maximum retry attempts indicate how many attempts 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, Integration Server waits the
length of the retry interval and then re‐executes the service using the original input
pipeline passed to the service. Integration Server continues to retry the service until the
service executes successfully or Integration Server makes the maximum number of retry
attempts. If the service throws an ISRuntimeException during the final retry attempt,
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, Integration Server adds an
entry to the audit log for each failed retry attempt. Each of these entries will have a
status of “Retried” and an error message of “Null”. However, if Integration Server
makes the maximum retry attempts and the service still fails, the final audit log entry
for the service will have a status of “Failed” and will display the actual error message.
Related Topics
 “About the Maximum Retry Period” on page 143
 “Setting Service Retry Properties” on page 144
About the Maximum Retry Period

Integration Server uses the same server thread for the initial service execution and the
subsequent retry attempts. 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, 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 Integration Server makes the maximum retry attempts. By
default, the maximum retry period is 15,000 milliseconds (15 seconds).
When you configure service retry, Integration Server verifies that the retry period for that
service will not exceed the maximum retry period. 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, Designer 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.

7 Building Services
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), Integration Server uses the trigger retry properties instead of the service
retry properties.
 UnlikeBroker/local triggers, you cannot configure a service to retry until successful.
 To catch a transient error and re‐throw it as an ISRuntimeException, the service must
do one of the following:
 If the service is a flow service, the service must invoke
pub.flow:throwExceptionForRetry. For more information about the
pub.flow:throwExceptionForRetry, see the webMethods Integration Server Built‐In Services
Reference.
 If the service is written in Java, the service can use
com.wm.app.b2b.server.ISRuntimeException ( ). For more information about
constructing ISRuntimeExceptions in Java services, see webMethods Integration
Server Java API Reference for the com.wm.app.b2b.server.ISRuntimeException
class.
 The service retry period must be less than the maximum retry period. For more
information, see “About the Maximum Retry Period” on page 143.
To configure service retry
1 In Package Navigator view, open the service for which you want to configure service
retry.
2 Under Transient error handling in the Properties view, in the Max retry attempts property,
specify the number of times Integration Server should attempt to re‐execute the
service. The default is 0, which indicates that Integration Server does not attempt to
re‐execute the service.
3 In the Max interval property, specify the number of milliseconds Integration Server
should wait between retry attempts. The default is 0 milliseconds, which indicates
that 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 Services to Retry” on page 142.

7 Building Services
Configuring Service Auditing

Service auditing is a feature in Integration Server that you can use to track which services
executed, when services started and completed, and whether services succeeded or
failed. You perform service auditing by analyzing the data stored in the audit log. The
audit log can contain entries for service start, service end, and service failure. The audit
log can also contain a copy of the input pipeline used to invoke the service. At run time,
services generate audit data at predefined points. Integration Server captures the
generated audit data and stores it in the audit log. If the audit log is a database, you can
reinvoke services using the webMethods Monitor.
Note: When Integration Server logs an entry for a service, the log entry contains the
identify of the server that executed the service. The server ID in the log entry always
uses the Integration Server primary port, even if a service is executed using another
(non‐primary) Integration Server port.
Each service has a set of auditing properties located in the Audit category on the service’s
Properties view. These properties determine when a service generates audit data and
what data is stored in the audit log. For each service, you can decide:
 Whether the service should generate audit data during execution. That is, do you
want the service to generate audit data to be captured in the audit log? If so, you must
decide whether the service will generate audit data every time it executes or only
when it is invoked directly by a client request (HTTP, FTP, SMTP, etc.) or a trigger.
 The points during service execution when the service should generate audit data to
be saved in the audit log. You might want a service to produce audit data when it
starts, when it ends successfully, when it fails, or a combination of these.
 Whether to include a copy of the service input pipeline in the audit log. If the audit
log contains a copy of the input pipeline, you can use the webMethods Monitor to
perform more extensive failure analysis, examine the service’s input data, or reinvoke
the service.
Keep in mind that generating audit data can impact performance. Integration Server uses
the network to send the audit data to the audit log and uses memory to actually save the
data in the audit log. If a large amount of data is saved, performance can be impacted.
When you configure audit data generation for services, you should balance the need for
audit data against the potential performance impact.
Note: The audit log can be a flat file or a database. If you use a database, the database
must support JDBC. You can use Integration Server to view the audit log whether it is
a flat file or a database. If the audit log is a database, you can also use the
webMethods Monitor to view audit data and reinvoke the service. Before you
configure service auditing, check with your Integration Server Administrator to learn
what kind of audit log exists. For more information about the audit log, see the
webMethods Logging Guide.

7 Building Services
Related Topics
 “Audit Properties” on page 350
 “Service Auditing Use Cases” on page 146
 “Setting Auditing Options for a Service” on page 148
Service Auditing Use Cases

Before you set properties in the Audit category on the Properties view, decide what type of
auditing you want to perform. That is, decide what you want to use the audit log for. The
following sections describe four types of auditing and identify the Audit properties you
would select to be able to perform that type of auditing.
Related Topics
 “Error Auditing” on page 146
 “Service Auditing” on page 147
 “Auditing for Recovery” on page 147
 “Auditing Long‐Running Services” on page 148
Error Auditing
In error auditing, you use the audit log to track and reinvoke failed services. To use the
audit log for error auditing, services must generate audit data when errors occur, and the
Integration Server must save a copy of the service’s input pipeline in the audit log.
With webMethods Monitor, you can only reinvoke top‐level services (those services
invoked directly by a client or by a 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 audit log contains the information needed to perform error auditing,
select the following Audit properties.
For this property... Select this option...

Enable auditing When top-level service only
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 audit log for error auditing, use a database as the audit log.

7 Building Services
Service Auditing
When you perform service auditing, you use the audit log to track which services execute
successfully and which services fail. You can perform service auditing to analyze the
audit log and determine how often a service executes, how many times it succeeds, and
how many times it fails. To use the audit log for service auditing, services need to
generate audit data after execution ends.
To make sure the audit log contains the information needed to perform service auditing,
select the following Audit properties.

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

Auditing for recovery involves using the audit log to track executed services and service
input data so that you can reinvoke the services. You might want to audit for recovery in
the event that a resource experiences a fatal failure, and you want to restore the resource
to its pre‐failure state by resubmitting service invocations.
When auditing for recovery, you want to be able to resubmit failed and successful
services. The audit log needs to contain an entry for each service invoked by a client
request or a trigger. The audit log also needs to contain a copy of each service’s input
pipeline.
To use the audit log to audit for recovery, select the following Audit properties.

Log on Error and success
Include pipeline Always
To use the audit log to audit for recovery, use a database for the audit log.

7 Building Services
Auditing Long-Running Services

If a service takes a long time to process, you might want to use the audit log to verify that
service execution started. If the audit log contains a start entry for the service but no end
or error entry, then you know that service execution began but did not complete. To
enable auditing of long‐running services, select the Error, success, and start option for the
Log on property.
Note: Typically, you will audit long‐running services in conjunction with error
auditing, service auditing, or auditing for recovery.
Setting Auditing Options for a Service

When you configure auditing for a service, you must determine if and when a service
generates audit data, and whether the audit log includes a copy of the service’s input
pipeline. Make sure that you select options that will provide the audit log with the audit
data you require.
Keep the following points in mind when configuring service auditing:
 Before you select options for generating audit data, check with your Integration
Server Administrator to determine what kind of audit log exists. An audit log can be
a flat file or a database.
 The options you select in the Audit category of the Properties view can be overwritten
at run time by the value of the watt.server.auditLog server property
 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.
 The pipeline data saved in the audit log is the state of the pipeline just before the
invocation of the service. It is not the state of the pipeline at the point the service
generates audit data.
 Including the pipeline in the audit log is more beneficial when the audit log is a
database. The Integration Server can save the pipeline to a flat file audit log; however,
you will not be able to use the pipeline data to reinvoke the service or perform failure
analysis.
 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 the webMethods Developer
User’s Guide.
 If you want audit events generated by a service to pass a copy of the input pipeline to
any subscribed event handlers, set Include pipeline to On errors only or Always.

7 Building Services
 To configure service auditing, you must have write access to the service and own the
lock on the service or have it checked out.
 For detailed information about the Audit properties, see “Audit Properties” on
page 350.
To set auditing options for a service
1 In the Package Navigator, double‐click the service for which you want to configure
service auditing.
2 In the Audit category of the Properties view, select an Enable auditing option to indicate
when you want the service to generate audit data.
3 For Log on, select an option to determine when the service generates audit data.
4 For Include pipeline, select an option to indicate when the Integration Server should
include a copy of the input pipeline in the audit log.
Assigning a Universal Name to a Service or 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 or document
type on an Integration Server.
The structure of a universal name is the same as the structure of a QName in an XML
namespace and consists of two parts: a namespace name and a local name.
 The namespace name is a qualifier that distinguishes a webMethods service from
other resources on the Internet. For example, there might be many resources with the
name AcctInfo. A namespace name distinguishes one AcctInfo resource from another by
specifying the name of the collection to which it belongs, similar to the way in which
a state or province name serves to distinguish cities with the same name (for example,
Springfield, Illinois, versus Springfield, Ontario).
Like namespaces in XML, the namespace portion of a universal name is expressed as
a URI. This notation assures uniqueness, because URIs are based on globally unique
domain names.
The namespace portion of the universal name can consist of any combination of
characters that form a valid absolute URI (relative URIs are not supported). For
example, the following are all valid namespace names:
http://www.gsx.com
http://www.gsx.com/gl/journals
http://www.ugmed.ch/résumè
For a complete description of what makes up a valid URI, see RFC 2396 Uniform
Resource Identifiers (URI): Generic Syntax.

7 Building Services
 The local name uniquely identifies a service or document type within the collection
encompassed by a particular namespace. Many webMethods users use a service’s
unqualified name as its local name. Under this scheme, a service named
gl.journals:closeGL would have a local name of closeGL.
Local names follow the same construction rules as NCNames in XML. Basically, a
local name can be composed of any combination of letters, digits, or the following
symbols:
. (period)
‐ (dash)
_ (underscore)
Additionally, the local name must begin with a letter or an underscore. The following
are examples of valid local names:
addCustOrder
authorize_Level1
générent
For specific rules relating to NCNames, see “NCName” definition in the Namespaces
in XML specification.
Related Topics
 “Universal Name Properties” on page 335
 “Implicit and Explicit Universal Names” on page 150
 “Deleting an Explicit Universal Name” on page 152
 “The Universal Name Registry” on page 152
 “Services You Use to Interact with the Universal Name Registry” on page 153
Implicit and Explicit Universal Names

Every service or document type that exists on Integration Server has an explicit or an
implicit universal name.
 An explicit universal name is a universal name that you specifically assign to a service or
document type with Designer. When you assign an explicit universal name, you must
specify both the namespace name and the local name.
 An implicit universal name is automatically derived from the name of the service or the
document type. The implicit name acts as the universal name when a service or
document type does not have an explicit universal name. 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.

7 Building Services
 The local name is the unqualified name of the service or document type.
The following table shows the implicit names for a variety of service names:
The service’s implicit universal name is...

Fully qualified service name Namespace name Local name
gl.journals:jrnlEntry http://localhost/gl.journals jrnlEntry

gl.journals.query:viewJournals http://localhost/gl.journals.query viewJournals
orders:postPO http://localhost/orders postPO
Note: It is possible for an implicit name to match the explicit name of another service.
When this condition exists, the explicit name takes precedence. That is, when a
universal name is requested, Integration Server searches its registry of explicit names
first. If it does not find the requested name there, it looks for a matching implicit
name.
Assigning, Editing, or Viewing an Explicit Universal Name

To ensure interoperability with other vendor’s implementations of SOAP, we recommend
that you always assign explicit universal names to those services or document types that
you want to make available to SOAP clients.
When you assign an explicit universal name, you must enter values in both the Namespace
name and Local name fields. If you specify one field but not the other, you will receive an
error message when you attempt to save the service or document type. You will not be
permitted to save it until you specify both parts of the universal name.
If you move a service or document type, or a folder containing a service or document type,
Designer retains the explicit universal name. If you copy a service or document type, or a
folder containing a service or document type, Designer does not retain the explicit
universal name.
Earlier versions of the webMethods SOAP implementation did not include the
http://localhost/ prefix as part of an implicit name. However, the server is backward
compatible. It will resolve QNames that clients submit in either the old form (without the
http prefix) or the new form (with the http prefix).
To assign, edit, or view a universal name
1 In Package Navigator view, double‐click 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.

7 Building Services
3 If you want to assign or edit the universal name, specify the following in the Universal
Name category of the Properties view:
In this field... Specify...
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 as the local name.
Deleting an Explicit Universal Name
To delete a universal name
1 In the Package Navigator, open the service or document type whose universal name
you want to delete.
2 In the Universal Name category of the Properties view, clear the settings in the
Namespace name and Local name fields.
The Universal Name Registry

Integration Server maintains a registry, called the Universal Name Registry, which maps
explicit universal names to the services and document types that they represent. The
registry is generated each time the Integration Server is started and is maintained in
memory while the server is running.
When you use the Designer to assign, modify, or delete a universal name, you update the
Universal Name Registry. To view the contents of the registry, you can execute the
service pub.universalName:list in Designer and view the contents of the names variable on
the Input/Output tab. (This service resides in the WmPublic package.)
Related Topics

7 Building Services
Services You Use to Interact with the Universal Name Registry

The following services can be used to display the Universal Name Registry or locate the
name of a service or document type associated with an explicit universal name. For more
information about these services, see the webMethods Integration Server Built‐In Services
Reference.
Service Description
pub.universalName:list Returns a document list containing the entries for the service
in the current registry. Each document in the list represents
an entry in the registry and contains a service’s fully
qualified webMethods name and both parts of its explicit
universal name.
pub.universalName:listAll Returns a document list containing the entries for services
and document types in the current registry. Each document
in the list represents an entry in the registry and contains the
fully qualified webMethods name and both parts of its
explicit universal name for each service and document type.
pub.universalName:find Returns the fully qualified service name for a specified
explicit universal name.
pub.universalName:findDoc Returns the fully qualified document type name for a
umentType specified explicit universal name.
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 Integration Server processes. These tags instruct 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.
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:

7 Building Services
 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). 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.
Important! In Designer, you can change the output template assigned to a service or
modify the existing output template. However, if you want to create a new output
template, use webMethods Developer.

8 Building Flow Services
 “What Is a Flow Service?” on page 155
 “Building Services Using the Tree Tab or Layout Tab” on page 160
 “Creating a New Flow Service” on page 160
 “Setting Properties for a Flow Step” on page 163
 “The INVOKE Step” on page 163
 “The BRANCH Step” on page 166
 “The REPEAT Step” on page 177
 “The SEQUENCE Step” on page 183
 “The LOOP Step” on page 185
 “The EXIT Step” on page 189
 “The MAP Step” on page 192
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
Integration Server, and/or services from a webMethods add‐on product such as the
webMethods JDBC Adapter.
You create flow services using Designer. They are saved in XML files on 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 Designer and webMethods
Developer. You cannot create or edit a flow service with a text editor.
Related Topics
 “What Is a Flow Step?” on page 156
 “What Is the Pipeline?” on page 158
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 163.
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 192.
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 166.
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 185.
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 177.

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 183.
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 189.
Related Topics
 “Inserting Flow Steps” on page 161
 “Flow Step Properties” on page 335
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 Designer to specify how information in the
pipeline is mapped to and from services in the flow.
Related Topics
 “What Does the Pipeline View Contain?” on page 194
 “Assigning Values to Pipeline Variables” on page 215
 “Dropping Variables from the Pipeline” on page 217
 “Adding Variables to the Pipeline” on page 218
 “Pipeline View Toolbar” on page 399

Building Services Using the Tree Tab or Layout Tab

In the flow service editor, you can view and build flow services using the Tree tab or
Layout tab.
 On the Tree tab, Designer lists flow steps sequentially from top to bottom, and
executes steps in that order. The Tree tab provides a more condensed view of a flow
service.
 On the Layout tab, a flow service looks similar to a flow chart. Designer displays flow
steps from left to right. Lines connect the flow steps and show the order in which the
flow steps execute. Designer displays shapes for flow steps as well as for the start and
end of the flow service. Steps such as BRANCH, LOOP, and REPEAT that can contain
child steps can be collapsed or expanded.
Because the Tree tab and Layout tab provide the same capabilities for building a flow
service, work in whichever tab you find easier to use. You can easily switch between the
tabs when building a flow service.
Designer uses the Tree tab as the default tab for building and viewing flow services. For
this reason, unless specifically stated otherwise, the procedures in the webMethods
Service Development Help are written for working in the Tree tab in the flow service
editor.
Creating a New Flow Service

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 XML document (a common flow‐
service function).
If you are building a flow service that extracts data from an 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.

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, Designer maps the incoming document to its
corresponding IS document type structure.
Important! The flow steps produced by this option are no different
than those produced by manually inserting INVOKE
pub.xml:loadXMLNode and INVOKE pub.xml:queryXMLNode steps in a flow
service. After Designer 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.
Related Topics
 “Package and Folder Requirements” on page 130
 “Creating New Elements” on page 34
 “Inserting Flow Steps” on page 161
 “Changing the Position of a Flow Step” on page 162
 “Changing the Level of a Flow Step” on page 162
Inserting Flow Steps

Flow steps call previously built services and direct the flow of data within a flow service.
You can use the button on flow service toolbar or the Palette view to insert flow steps
into a flow service.
The Palette view is located at the right of the flow service editor. Click to show the
Palette view. Click to hide the Palette view.
To insert a flow step
1 In the Package Navigator view, open the flow service in which you want to insert
flow steps.
 Click the button next to on the flow service editor toolbar and select the

flow step that you want to insert.
 In the Palette view, select the flow step that you want to insert and drag it to the
flow service editor.

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 on the Tree tab , 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.
Changing the Level of a Flow Step

Some flow steps have subordinate steps on which they operate. Subordinate steps are
referred to as children. For example, when you use the LOOP step, the set of steps that
make up the loop are referred to as children of that LOOP step.
Children are specified by indenting them beneath their parent flow step. In the following
example, the top LOOP step has three children. Note that 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
LOOP step.
These steps are
“children” of the
BRANCH step.
To promote or demote a flow step within a parent/child hierarchy, select the step on the
Tree tab, 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 Properties for 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 view. Values that you specify in the Properties view
apply only to the selected step in the editor.
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 166 and “The EXIT Step” on page 189
for additional information about this use of the label property.
Related Topics
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.
Related Topics
 “INVOKE Properties” on page 375
 “Specifying the Service Property” on page 164
 “Invoking a Built‐In Service” on page 164
 “Invoking a Service on Another Integration Server” on page 165
 “Building an Invoke Step” on page 165
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, Designer 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
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 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 where you want to insert the INVOKE step.
 Click the button next to on the flow service editor toolbar and click . In

the Open dialog box, navigate to the service you want to invoke.
 Click by the side of the flow service editor to open the Palette view and select
the flow step that you want to insert and drag it to the flow service editor.
 Select one or more services in Package Navigator view and drag 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 view:
For this property... Specify...
Service The fully qualified name of the service that will be invoked at run
time. When you insert a service, Designer automatically assign
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. The maximum number of seconds that this step should
run. If this time elapses before the step completes, the server
waits for the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols. For
example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout
blank.
Validate input Whether or not you want the server to validate the input to the
service against the service input signature. Select True to validate
the input. Select False if you do not want to validate the input.
Validate output Whether or not you want the server to validate the output of the
service against the service output signature. Select True to validate
the output. Select False if you do not want to validate the output.
4 If necessary, on the Pipeline view, 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 197.
Tip! In Designer, clicking the button next to or opening the Palette view

displays a list of commonly used services. You can edit the Window > Preferences >
Software AG > Service Development > Flow Service Editor preferences 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.
Related Topics
 “BRANCH Properties” on page 373
 “Branching on a Switch Value” on page 167
 “Branching on an Expression” on page 170
 “Branching on Null and Empty Values” on page 171
 “Specifying a Default Step” on page 172
 “Using a SEQUENCE as the Target of a BRANCH” on page 173
 “Building a BRANCH Step” on page 175
 “Building a BRANCH Step” on page 175
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 view 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 Value” on page 168.
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 168.

Simple BRANCH step that branches on a switch value
Each conditional step has a The switch property of the BRANCH

label that matches the value step specifies the name of the
that causes it to execute. variable that acts as the switch.
Specifying the Switch Value

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 the webMethods Developer User’s Guide.
Unlike other flow steps whose children execute in sequence at run time, only one child of
a BRANCH step is executed: the target whose label matches the value of the switch
variable. If none of the targets match the switch variable, none of them are performed,
and execution “falls through” to the next step in the flow service. For example, in the
following flow service, execution passes directly to the LogTransaction service if the value
of PaymentType is “COD.”

An unmatched value will fall though the BRANCH
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 171.
 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 171.
 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 172.

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 view 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 the webMethods Developer User’s Guide.
Simple BRANCH step that branches on an expression
Each target step When set to True, the Evaluate

has an expression label property indicates the step
as the label. 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 172.
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, Integration 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 the
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 ...and the $default

handle credit card and target step handles
corporate account payments... the rest.
Important! You can only have one default target step for a BRANCH step. Designer
always evaluates the default step last. The default step does not need to be the last
child of the BRANCH step.
Using a 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 183.

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.
 Click the button next to on the flow service editor toolbar and click .
 Click by the side of the flow service editor to open the Palette view. Click
and drag it to the flow service editor.
Comments An optional descriptive comment for this step.
Scope The name of a document (IData object) in the pipeline to which
you want to restrict this step. If you want this step to have access
to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run. If
this time elapses before the step completes, the server waits for
the step to complete and then raises an exception.
property, type the variable name between % symbols (for
example, %expiration%).
blank.
Label An optional name for this specific step, or a null, unmatched, or
empty string ($null, $default, blank). For more information about
branching on null or empty values, see “Branching on Null and
Empty Values” on page 171.
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 189.
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 by clicking the button next to on the flow service editor

toolbar and clicking the required flow step.
b Indent the flow step using on the flow service editor toolbar to make it a child
of the BRANCH step.
c In the Label property on the Properties view, 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.
Related Topics
 “REPEAT Properties” on page 380
 “Specifying the REPEAT Condition” on page 178
 “Setting the REPEAT Counter” on page 178
 “When Does REPEAT Fail?” on page 178
 “Using REPEAT to Retry a Failed Step” on page 179
 “Using REPEAT to Retry a Successful Step” on page 181

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.
 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 to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run. If
blank.
Label An optional name for this specific REPEAT step, or a null,
unmatched, or empty string ($null, $default, blank).
Important! If you use this step as a target for a BRANCH or
EXIT step, you must specify a value in the Label property. For
more information about the BRANCH and EXIT steps, see
“The BRANCH Step” on page 166 or “The EXIT Step” on
page 189.
Count The maximum number of times you want the children to be
re‐executed. If you want to use the value of a pipeline variable
for this property, type the variable name between % symbols
(for example, %servicecount%).
If you want the children re‐executed until they are all
successful (that is, no maximum limit), set this value to –1.
Repeat interval The length of time (in seconds) that you want the server to
wait between iterations of the children.
example, %waittime%).
Repeat on FAILURE

4 Beneath the REPEAT step, use the following steps to insert each step that you want to
repeat:
a Insert a flow step using the buttons on the flow service editor toolbar.
b Indent that flow step using on the flow service 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.

Timeout The maximum number of seconds that this step should run.If
blank.
Label An optional name for this specific step, or a null, unmatched,
or empty string ($null, $default, blank).
EXIT step, you must specify a value in the label property. For
page 189.
Count The maximum number of times you want the children to be
re‐executed. If you want to use the value of a pipeline variable
for this property, type the variable name between % symbols
(for example, %servicecount%).
If you want the children re‐executed until any one of them
fails (that is, no maximum limit), set this value to –1.
Repeat interval The length of time (in seconds) that you want the server to
wait between iterations of the children.
example, %waittime%).
Repeat on SUCCESS

4 Beneath the REPEAT step, use the following steps to insert each step that you want
repeat:
b Indent that flow step using on the editor toolbar to make it a child of the
REPEAT step.
The SEQUENCE Step

You use the SEQUENCE step to build a set of steps that you want to treat as a group.
Steps in a group are executed in order, one after another. By default, all steps in a flow
service, except for children of a BRANCH step, are executed as though they were
members of an implicit SEQUENCE step (that is, they execute in order, one after
another). However, there are times when it is useful to explicitly group a set of steps. The
most common reasons to do this are:
 To group a set of steps as a single alternative beneath a BRANCH step. For details
about this use of the SEQUENCE step, see “Using a SEQUENCE as the Target of a
BRANCH” on page 173.
 To specify the conditions under which the server will exit a sequence of steps without
executing the entire set.
Related Topics
 “SEQUENCE Properties” on page 382
 “Using SEQUENCE to Specify an Exit Condition” on page 183
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.
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.
Related Topics
 “LOOP Properties” on page 377
 “Specifying the Input Array” on page 186
 “Collecting Output from a LOOP Step” on page 187
 “Building a LOOP Step” on page 188
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 view. 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…
Timeout The maximum number of seconds that this step should run.If
blank.
Label An optional name for this specific LOOP step, or a null,
EXIT step, you must specify a value in the Label property. For
page 189.
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, or 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 flow service editor toolbar to make it a child
of the LOOP step.
5 Use the Pipeline view 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 view, see “Mapping Data in Flow Services” on page 193.
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
debug the step in Designer 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.
Related Topics
 “EXIT Properties” on page 374
 “Building an EXIT Step” on page 190
Building an EXIT Step

Use the following procedure to build an EXIT step in a flow service
To build an EXIT step
1 If you are inserting an EXIT step into an existing flow service, display that service in
the editor and select the step immediately above where you want the EXIT step
inserted.

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 166.
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%).
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 “Mapping Data in Flow Services” on
page 193.
Related Topics
 “MAP Properties” on page 379

9 Mapping Data in Flow Services
Because systems rarely produce data in the exact format that other systems need, you
commonly need to build flow services that perform data transformations. Data
transformation resolves differences in the way data is represented within documents that
applications and systems exchange. In Designer, data transformations can be
accomplished by mapping data. By mapping, you can accomplish the following types of
transformations:
 Name transformations. This type of transformation resolves differences in the way data
is named. 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 structure remains the same, but the name of the variable
changes.
 Structural transformations. This type of transformation resolves differences in the data
type or structure used to 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 nested in a Document named customerInfo. 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 structure changes.
 Value transformations. This type of transformation resolves differences in the way
values are expressed (for example, when systems use different notations for values
such as standard codes, units of currency, dates, or weights and measures). 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.
Related Topics
 “What Does the Pipeline View Contain?” on page 194
 “Basic Mapping Tasks” on page 196
 “Linking Variables” on page 197
 “Assigning Values to Pipeline Variables” on page 215
 “Dropping Variables from the Pipeline” on page 217

 “Adding Variables to the Pipeline” on page 218
 “Working with Transformers” on page 220
What Does the Pipeline View Contain?

The Pipeline view 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 view to
route variables (data) between services or between document formats.
The Pipeline view displays the pipeline for invoked services (INVOKE steps) or MAP
steps in a flow service. The contents of the Pipeline view are different for INVOKE steps
than for MAP steps.
Related Topics
 “Pipeline View for an INVOKE Step” on page 194
 “Pipeline View for a MAP Step” on page 195
Pipeline View for an INVOKE Step

For an INVOKE step, the Pipeline view depicts two stages of the pipeline with respect to
the selected service in the editor.
Pipeline view for an INVOKE step

The Pipeline view 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).
In the Pipeline view, 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.
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).
In the Pipeline view, 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: Designer displays small symbols next to a variable icon to indicate validation
constraints. Designer uses to indicate an optional variable. Designer 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 304.
Pipeline View for a MAP Step

For a MAP step, the Pipeline view displays a single stage of the pipeline. The Pipeline
view contains two sets of variables: Pipeline In and Pipeline Out. Between these sets of
variables, the Pipeline view contains a column named Transformers.

Pipeline view 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 “Working with Transformers” on page 220.
 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.
Basic Mapping Tasks

Basic mapping tasks are the tasks you perform to manage the pipeline contents and the
values of variables in the pipeline. In the Pipeline view, 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).

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. Designer connects service and pipeline variables
in the Pipeline view 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, Designer 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. Designer 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.
Note: The Pipeline view 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 view to explicitly link the variables to each other. Explicit
linking is how you accomplish name and structure transformations required in a flow.
Designer connects explicitly linked variables with a solid black line.
On the input side of the Pipeline view, use 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 .

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, link the
variables 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,
link the variables to
connect them.
Designer
automatically adds a
service’s output
variables to the
pipeline and implicitly
links them.
Related Topics
 “Link Properties” on page 345
 “Assigning Properties to Variables” on page 302
 “Creating a Link Between Variables” on page 200
 “What Happens When Integration Server Executes a Link?” on page 201
 “Linking to Document and Document List Variables” on page 204
 “Linking Variables of Different Data Types” on page 204
 “Linking to and from Array Variables in the Pipeline” on page 207
 “Deleting a Link Between Variables” on page 212
 “Linking Variables Conditionally” on page 213

Creating a Link Between Variables

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 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?” on page 201.)
 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
in the Pipeline” on page 207. For more information about placing conditions on links
between variables, see “Linking Variables Conditionally” on page 213.
 You cannot create a link to a variable if you already assigned a value to a variable.
 After a link executes, 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 flow service editor, select the INVOKE or MAP step containing the variables
you want to link.
2 Open the Pipeline view.
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 Pipeline view 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, Designer
prevents you from creating a link between the variables and 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 in the Pipeline” on page 207.
 If you want to place a condition on the execution of the link, see “Linking Variables
Conditionally” on page 213.
 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.
What Happens When Integration Server Executes a Link?

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, 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 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.)
Related Topics
 “Example of Copying By Reference” on page 202
 “Preventing Pipeline Values from Being Overwritten” on page 203
Example of Copying By Reference

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.
Preventing Pipeline Values from Being Overwritten

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 as demonstrated in
“Example of Copying By Reference” on page 202, 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, its children cannot be the targets of
links.
 After the child variable of a Document or Document List is the target of a link, the
parent Document or Document List cannot be a target of a link.
 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

In the Pipeline view, 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, Designer will not
allow you to link them to each other.

 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 the following:
 Any variable can be linked to an Object or an Object List variable
 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, 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 Designer 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 386.
 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, Designer uses the
default behavior to determine the value of the target variable.
Related Topics
 “Converting a String List to a Document List in the Pipeline” on page 205
 “Converting Two String Lists to a Document List in the Pipeline” on page 206
 “Default Pipeline Rules for Linking to and from Array Variables” on page 209
 “Java Classes for Objects” on page 386
Converting a String List to a Document List in the Pipeline

You can convert a String List to a Document List in the pipeline by mapping a String List
to a String in a Document List. In the following image, 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
Converting Two String Lists to a Document List in the Pipeline

Two String Lists can be combined into one Document List in the pipeline by linking each
String List to a String nested in a Document List. For example, suppose that you had
String List variables named aList and 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
“Working with Transformers” on page 220. For more information about built‐in
services, see the webMethods Integration Server Built‐In Services Reference.

Linking to and from Array Variables in the Pipeline

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: Designer uses blue links in the Pipeline view to indicate that properties
(conditions or index values for arrays) have been applied to the link between
variables.
Related Topics
 “Creating a Link to or from an Array Variable” on page 208
 “Default Pipeline Rules for Linking to and from Array Variables” on page 209
Creating a Link to or from an Array Variable

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, Designer
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; 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 view will be used. For information about the
default behavior of the Pipeline view, see “Default Pipeline Rules for Linking to and
from Array Variables” on page 209.
 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 204.

 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). Integration Server generates journal log messages (at debug level 6 or
higher) when links to or from array variables fail.
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 “Creating a Link
Between Variables” on page 200.
2 In Pipeline view, click the link that connects the variables.
3 In the Properties view, click the Indices value and click . The Link Indices dialog box

appears.
4 If the source variable is an array variable, under Source, type the index that contains
the value you want to link. If the source variable is a String Table, you need to specify
a row index and a column index.
5 If the target variable is an array variable, under Destination, type the index to which
you want to link the source value. If the target variable is a String Table, you need to
specify a row index and a column index.
6 Click OK.
Related Topics
 “Linking to Document and Document List Variables” on page 204
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,
Designer uses the default rules in the Pipeline view 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
Deleting a Link Between Variables

When you delete link in Pipeline view, the variables are no longer linked. Designer also
deletes any properties you applied to the link.
To delete a link between variables
1 In the flow service editor, select the INVOKE or MAP step containing the variables
with the link you want to delete.
2 In the Pipeline view, select the link that you want to delete.
3 Click Edit > Delete.
Tip! You can also delete a link by selecting it and then pressing the DELETE key.

Linking Variables Conditionally

You can place conditions on the links you draw between variables. At run time,
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
Designer 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 link two variables, 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 view
to view or create
a condition for
the link.
Designer uses a blue link in the Pipeline view 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.
Related Topics
 “Linking Multiple Source Variables to a Target Variable” on page 214
 “Applying a Condition to a Link” on page 214

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, 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. 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 166.
Related Topics
 “Linking Variables Conditionally” on page 213
 “Applying a Condition to a Link” on page 214
Applying a Condition to a Link

Keep the following points in mind when making a conditional link:
 You can only add conditions to the links between explicitly linked variables. You
cannot add conditions to the links between implicitly linked variables.
 When drawing more than one link to the same target variable, make sure that the
conditions assigned to each link are mutually exclusive.
 You can temporarily disable the condition placed on a link. For more information, see
“Disabling and Enabling Conditions” on page 250.
To apply a condition to the link between variables
1 Create a link between the variables using the procedure described in “Creating a Link
Between Variables” on page 200.
2 In Pipeline view, click the link that connects the variables.
3 In the Properties view, 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 the webMethods Developer
User’s Guide.

Related Topics
 “Disabling and Enabling Conditions” on page 250
Assigning Values to Pipeline Variables

You can assign values to variables in Service In or Pipeline Out using on the Pipeline
view toolbar. You can do this to:
 Explicitly “hard code” a specific value in a variable.
 Initialize a set of input variables by assigning values to all of the input variables.
 Assign a default value to a variable. That is, a value that is only assigned if the variable
is null at run time.
 Assign a variable the value of another pipeline variable by referencing the variable.
(You might do this if you wanted to derive the default variable value from another
variable in the pipeline at run time.)
By using to assign a value 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).
Related Topics
 “Setting a Value for a Pipeline Variable” on page 215
 “Copying Assigned Values Between Pipeline Variables” on page 216
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 explicitly linked to another value in
the pipeline, you cannot assign a value to the variable. If the variable is implicitly
linked, you can 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, Designer automatically validates the
values. If the value is not of the type specified by the Object constraint, Designer
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 [ ].
 You can 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.
To assign a value to a variable in the pipeline
1 In the flow service editor, select the INVOKE or MAP step containing the variable
you want to alter.
2 In Pipeline view, select the variable to which you want to assign a value.
3 Click on the toolbar.
4 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.
5 If you want Integration 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, Integration Server will always apply the specified value.)
Copying Assigned Values Between Pipeline Variables

You can copy the value assigned to a variable by copying the icon next to the variable.
You can assign this value to other variables of the same data type in Service In or Pipeline
Out by pasting the icon.
When you copy assigned 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 flow service editor, select the INVOKE or MAP step containing the variable
with the value you want to copy and paste.
2 In the Pipeline view, select the assigned value icon that you want to copy.
3 Right‐click and select Copy.
4 Select the variable to which you want to assign the copied value, right‐click and select
Paste.
Dropping Variables from the Pipeline

You can remove a variable from Pipeline In or Pipeline Out by dropping the variable. You
can drop variables 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,
which can make the Pipeline view 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 drop a variable unless you are sure the
variable is not used by services invoked after the point where you drop it.
At run time, Integration Server removes a dropped variable from the pipeline just before
it executes the selected service (if you drop a variable in Pipeline In) or immediately after it
executes the selected service (if you drop a variable in Pipeline Out).
If you drop a linked variable from Pipeline In, Integration Server executes the link before it
drops the variable. However, Integration Server server does not link a null value to the
destination variable.
Related Topics
 “Dropping a Pipeline Variable” on page 218

Dropping a Pipeline Variable

Keep the following points in mind when dropping variables from the pipeline:
 You can only drop variables from Pipeline In and Pipeline Out. In a MAP step, you can
only drop variables from Pipeline In.
 Once you drop a variable from the pipeline, it is no longer available to subsequent
services in the flow. Do not drop a variable unless you are sure the variable is not
used by services invoked after the point where you drop it.
To drop a variable from the pipeline
1 In the flow service editor, select the INVOKE or MAP step whose pipeline variables
you want to drop.
2 In the Pipeline view, select the variable that you want to drop.
3 Click on the toolbar.
Adding Variables to the Pipeline

In the Pipeline view, you can add variables that were not declared as input or output
parameters for the flow service itself or any of its constituent services. You can 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 add to the pipeline can be used just like any declared variable in the
flow.
Related Topics
 “Adding a Pipeline Variable” on page 218
 “Copying Assigned Values Between Pipeline Variables” on page 216
Adding a Pipeline Variable

Keep the following points in mind when adding variable to the pipeline:
 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, Designer automatically clears it from the
pipeline.

 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 in the Pipeline view 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 flow service editor, select the INVOKE or MAP step that represents the stage of
the pipeline at which you want to add a new variable.
2 Do one of the following in the Pipeline view:
 Select the point in the pipeline where you want to add the new variable (Pipeline
In, Service In, Service Out, or Pipeline Out). Click and select the type of variable
that you want to create.
 In the Palette view that is part of Pipeline view, under Variables, select the
variable that you want to add and then select the point in the pipeline where you
want to add it. The Palette view is located within the Pipeline view. Click to
show the Palette view. Click to hide the Palette view.
3 Type a name for the variable and press ENTER.
4 With the variable selected, set variable properties and apply constraints using the
Properties view.
5 If the variable is a Document or a Document List, repeat step 2 to define its member
variables. Then use to indent each member variable beneath the Document or
Document List variable.
6 Do one of the following with the new variable:
 Link the variable to another variable.
 Assign a value to the variable using on the Pipeline view toolbar.
 Drop the variable.
Important! If you do link the variable, assign a value to it, or drop it, Designer
considers it extraneous to the flow and automatically clears the variable when it
refreshes the Pipeline view.
Related Topics

Working with Transformers

Transformers are the services you use to accomplish value transformations in the Pipeline
view. 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.
You can think of transformers as a collection of INVOKE steps embedded in a single
MAP step. 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.
Related Topics
 “Transformer Properties” on page 356
 “Using Built‐In Services as Transformers” on page 221
 “Inserting a Transformer” on page 221
 “Linking Variables to a Transformer” on page 223
 “Transformers and Array Variables” on page 224
 “Validating Input and Output for Transformers” on page 225
 “Validating Input and Output for Transformers” on page 225
 “Copying Transformers” on page 226
 “Renaming Transformers” on page 227
 “Debugging Transformers” on page 228

Using Built-In Services as Transformers

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.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.
Related Topics
Inserting a Transformer
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 Integration Server executes
the transformers concurrently at run time.
 In a MAP step, Designer only displays the links between pipeline variables and
transformers. Designer does not display any implicit linking for a MAP step.
To insert a transformer

1 In the flow service editor, select the MAP step in which you want to insert a
transformer.
2 In the Pipeline view, do one of the following:
 Click the button adjacent to on the Pipeline view toolbar and select the

service you want to use as a transformer. If the service you want to insert does not
appear in the list, click Browse to select a service on Integration Server.
 In the Palette view that is located within the Pipeline view, select the folder
containing the service you want to add as a transformer. Select the service and
click in the Transformers area of Pipeline view.
 In Package Navigator view, select the service you want to use as a transformer
and drag it to the Transformers area of Pipeline view.
3 To set properties for the transformer, select it and then specify the following
information in the Properties view:
Service The fully qualified name of the service that will be invoked at
run time as a transformer. When you insert a transformer,
Designer 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 Integration Server validates the input to the
transformer against the signature of the service. Select True to
validate the input of the transformer, otherwise select False.
Validate output Whether Integration Server validates the output of the
transformer against the signature of the service. Select True to
validate the output of the transformer, otherwise select False.
4 Link pipeline variables to the transformer variables. See “Linking Variables to a
Transformer” on page 223.
Related Topics
 “Validating Input and Output for Transformers” on page 225.
 “Debugging Transformers” on page 228.

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:
 You must explicitly link pipeline variables to the input and output variables of a
transformer. Designer does not perform any implicit linking with transformers. Even
if the pipeline variables have the same name and data type as the transformer
variables, no implicit linking occurs.
 Designer 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, you need to explicitly
link the output variable to a Pipeline Out variable.
 If you do not link any output variables or the transformer does not have any declared
output variables, the transformer service will not run.
 You can link a transformer output variable to more than one Pipeline Out variable.
 You can assign a value to a transformer input value using on the Pipeline view
toolbar.
 To prevent the Pipeline view from becoming cluttered, the Pipeline view may not
display all the links between the transformer and the pipeline variables. To view all
the links, double‐click the transformer or click next to the transformer name.
Use the following procedure to link pipeline and transformer variables when the
transformer is not expanded. If the transformer is expanded (that is, you can see all of the
input and output variables for the transformer), you link variables just as you would for
an INVOKE step.
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 collapsed transformer. Designer displays the Link dialog
box.
b In the Link To list, select the transformer variable to which you want to link the
Pipeline In variable.
In the Link To list, Designer displays the phrase “has already been chosen” next to
variables that are already linked to other variables transformer.
c Repeat steps a and b for each transformer input variable you want to link to a
pipeline variable.

2 To create a link between a transformer output variable and a Pipeline Out variable, do
the following:
a Select the collapsed transformer and drag your mouse to the variable in Pipeline
Out to which you want to link the transformer variable. Designer displays the Link
dialog box.
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.
Transformers and Array Variables

When creating links between pipeline variables and transformers, dimensional
differences between the source and target variables may cause an exception. If the target
variable dimensionality is greater than the source variable dimensionality, an exception
will not be thrown. However, if the source variable dimensionality is greater than the
target variable dimensionality, Integration Server throws an exception.
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 of Dimensionality Mismatch

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
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 Integration Server validates a transformer’s inputs and outputs at run time,
Integration Server validates the transformer input and output values against the
signature of invoked service. Variables in the service signature may specify content or
structural constraints.

Note: If the Validate input and/or Validate output check boxes are selected on the

Input/Output tab of the service acting as a transformer, Integration Server
automatically validates the input and/or output for the service every time the service
executes. If you set up validation via the properties for a transformer when it is
already set up for validation via the service’s Input/Output tab, Integration Server
performs validation twice. This can slow down the execution of a transformer and,
ultimately, the flow service.
To specify input/output validation for a transformer
1 In the flow service editor, select the MAP step containing the transformer you want to
validate.
2 In the Pipeline view, under Transformers, select the transformer for which you want to
specifying input/output validation.
3 In the Properties view, do the following:
 If you want Integration Server to perform input validation, set the Validate input
property to True.
 If you want Integration Server to perform input validation, set the Validate output
property to True.
Related Topics
 “Applying Constraints to Variables” on page 304
 “Declaring a Service Signature” on page 130
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
inserting the service repeatedly, you can copy and paste the transformer service.
 You can copy transformers between MAP steps in the same flow or MAP steps in
different flow services.
 You can copy multiple transformers at a time.
 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 .

To copy a transformer
1 In the flow service editor, select the MAP step containing the transformer service you
want to copy.
2 In the Pipeline view, under Transformers, select the transformer that you want to copy.
Right‐click and select Copy.
 To paste the transformer in the same MAP step, right‐ click anywhere under
Transformers and select Paste.
 To paste the transformer in another MAP step, select that MAP step. In Pipeline
view, right‐ click anywhere under Transformers and select Paste.
4 Link the input and output variables of the transformer. See “Linking Variables to a
Transformer” on page 223.
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
“Setting Dependency Checking Safe Guards” on page 39.
To rename a transformer
1 Use Package Navigator view 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 flow service editor, select the MAP step containing the transformer. Then, in
Pipeline view, select the transformer you want to rename.
4 In the Service property in the Properties view, 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 debug a flow service, you can use the following 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 “Stepping Into and Out of
a MAP Step” on page 243.
 Set a breakpoint on a transformer so that service execution stops when the
transformer is encountered. For more information about setting breakpoints, see
“Setting and Removing Breakpoints” on page 246.
 Disable a transformer so that it does not execute at run time. For more information
about disabling transformers, see “Disabling Flow Steps, Transformers, and
Conditions” on page 249.

10 Running and Debugging Flow Services
Designer provides a range of tools to assist you during the debugging phase of
development. For example, you can:
 Run 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, execute its steps one at a time, specify points where you want to halt
execution, and examine and modify the pipeline before and after executing
individual flow service steps.
Related Topics
 “Using Launch Configurations while Running and Debugging Services” on page 229
 “Supplying Input Values to a Service” on page 232
 “Running a Flow Service” on page 235
 “About Debugging Flow Services” on page 236
 “Stepping Through Flow Services” on page 241
 “Using Breakpoints” on page 245
 “Disabling Flow Steps, Transformers, and Conditions” on page 249
 “Modifying the Pipeline while Debugging” on page 251
 “Saving and Restoring the Pipeline while Debugging” on page 254
 “Viewing Service Results” on page 257
Using Launch Configurations while Running and Debugging

Services
In Designer, you create launch configurations to run and debug services. A launch
configuration contains the information Designer needs to execute a service. You can
create one or more launch configurations for each service.
You can use the same launch configurations to run and debug services. When using a
launch configuration to run a service, Designer invokes the service (just as an ordinary IS
client would) and receive its results. The service executes once, form beginning to end (or
until an error condition forces it to stop) on the Integration Server on which the service
resides. When using a launch configuration to debug a service, Designer stops at the first
flow step (the default) or executes the service until it encounters a breakpoint.

Designer requires launch configurations to run and debug service. However, if a service
does not have an associated launch configuration and you bypass the Run Configuration
or Debug Configuration dialog boxes when running or debugging the service, Designer
creates one on the fly and saves it in your workspace. You can use this configuration from
one session to the next. In fact, Designer reuses this configuration every time you run or
debug the service without creating a launch configuration.
By default, Designer saves launch configurations in your workspace. However, you
might want to share launch configurations with other developers. You can specify that
Designer save a launch configuration to a shared file. On the Common tab in the Run
Configurations dialog box or Debug Configurations dialog box, select the Shared file
option and provide a workspace location in which to save the file.
You might consider creating a launch configuration for each set of data that you routinely
use to debug your service. 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 workspace project directory just for holding sets of test data
that they generate in this manner.
Related Topics
 “Creating a Launch Configuration” on page 230
Creating a Launch Configuration

Use the following procedure to create a launch configuration for use in running or
debugging a service.
To create a launch configuration for a service
1 In Designer
Run > Run Configurations
–or–
Run > Debug Configurations
2 In the Run Configuration or Debug Configuration dialog box, select IS Service and click

to add a new launch configuration.
3 In the Name field, specify a name for the launch configuration
4 On the Service tab, in the Integration Server list, select the Integration Server on which
the service for which you are creating a launch configuration resides.
5 In the Service field, enter the name of the service for which you are creating a launch
configuration of click Browse to select the service.

6 If you want Designer to stop at the first flow step when executing the launch
configuration in a debug session, select the Stop at first flow step check box.
If you clear the Stop at first flow step check box, during a debug session, Designer
executes the service until the service ends or hits a breakpoint. If you want to debug
the service by stepping through one flow step at a time, select the Stop at first flow step
check box.
7 If you want Designer to pass the service an IData that contains input values for each
input variable in the service signature, do the following:
a On the Input tab, select Use IData.
b Specify the input values to save with the launch configuration by doing one of the
following:
 Type the input value for each service input parameter. For more information
about providing input values, see “Entering Input for a Service” on page 232.
 To load the input values from a file, click Load to locate and select the file
containing the input values. If Designer cannot parse the input data, it
displays an error message indicating why it cannot load the data. For more
information about loading input values from a file, see “Loading Input
Values” on page 235.
Designer validates the provided input values. If provided values do not match the
input parameter data type, Designer displays a message to that effect. You cannot
use the launch configuration to run or debug the service if the provided input
does not mach the defined data type.
c If you want to pass empty variables (variables that have no value) to the service,
select the Include empty values for String Type check box. When you select this option,
empty strings are passed with a zero‐length value. If you do not select this option,
Designer excludes empty value from the IData it passes to the service as input.
d If you want Designer to give the user executing the launch configuration the
option of providing different input values than those saved with the launch
configuration, select the Prompt for data at launch check box. If you clear this check
box, Designer passes the service the same set of data every time the launch
configuration executes. Designer does not give the user the opportunity to change
the input values when the launch configuration executes
8 If you want Designer to send the flow service an XML document a input, do the
following:
a Select Use XML.
b In the Location field, enter the path and file name of the XML document to use as
input or click Browse to locate and select the XML file.
Designer displays the contents of the XML document on the Input tab.
9 If you selected the Use IData option and 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.

10 Click Apply.
11 If you want execute the launch configuration in run or debug mode, click the
appropriate button. Otherwise, click Close.
Related Topics
 “Saving Input Values” on page 234
 “Loading Input Values” on page 235
 “Saving the Pipeline while Debugging” on page 254
 “Saving the Service Results” on page 260
Supplying Input Values to a Service

When you create a launch configuration, run a service, or debug a service you need to
pass input to the service. You can provide a value for every input parameter in the service
signature or you can pass the service an XML document. You can save a set of input
values to a file and reuse them in later tests or with other launch configurations.
Related Topics
 “Entering Input for a Service” on page 232
Entering Input for a Service

When you create a launch configuration for a service, run a service, or debug a service
Designer provides a screen in which you can enter an input value for each variable in the
service’s input signature.
Keep the following points in mind when providing input values for a service:
 You can enter input values for String type variables and document and document
lists that contain string‐based children.
 You can enter input values for constrained object variables.
When you enter values for constrained objects, Designer automatically validates the
values. If the value is not of the type specified by the object constraint, Designer
displays a message identifying the variable and the expected type.

 Object variables without constraints are noted as “Not editable by user.”
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 as input. 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 debug) and
use that harness to test your service.
 When you execute a launch configuration, Designer prompts you for input values
only if the Prompt for data at launch check box is selected in the launch configuration. If
this check box is cleared, Designer passes the service the same set of data every time
the launch configuration executes. Designer does not give you the opportunity to
change the input values when the launch configuration executes
 Designer validates the provided input values. If provided values do not match the
input parameter data type, Designer displays a message to that effect. You cannot use
the launch configuration to run or debug the service if the provided input does not
mach the defined data type.
To enter input values for a service
1 Open a launch configuration for the service or run or debug the service as described
in “Creating a Launch Configuration” on page 230, “Running a Flow Service” on
page 235, or “About Debugging Flow Services” on page 236.
2 To load input values from a file, do one of the following:
 If you are working with a launch configuration, on the Input tab click Load.
 If you are running or debugging a service, in the Enter Input for serviceName dialog
box, click Load Inputs.
3 On the Input tab (if you are creating a launch configuration) or in the Enter Input for
serviceName dialog box (if you are running or debugging the service), enter a value for
each input variable.
If the service takes complex variables such as String lists, String tables, 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.

Use this... To...
Delete the selected row from the variable.
Delete the selected column from the variable.
4 If you want Designer 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.
5 To save the input values to a file for use in later debugging, click Save or Save Inputs or
Save. In the Save As dialog box, specify the name and location of the file to which you
want the values saved. Click Save.
Related Topics
 “Debugging a Flow Service” on page 240
Saving Input Values

You can save the input values that you provide when creating a launch configuration or
when running or debugging a service to a file. This enables you to reuse them in later
tests or in other launch configurations.
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,
Designer does not save empty variables in the file.
 You can store the file in any directory that is accessible to the computer on which
Designer 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.
 Designer saves the data in XML format
Related Topics

Loading Input Values

When creating a launch configuration or running or debugging a service, you can reload
input values that you have saved to a file instead of rekeying the values each time.
When you use input values from a file, keep the following points in mind:
 Designer 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 tab or Enter Input dialog box.
 Variables that exist in the Input tab or Enter Input dialog box, but not in the file, are set
to null.
 Besides loading values saved via the launch configuration or Enter Input dialog box,
you can also load values that were saved using pub.flow:savePipelineToFile service. In
addition, you can change values in the pipeline during debugging.
Related Topics
Running a Flow Service

When you run a service, Designer 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.
Results from the service are returned to Designer and displayed in Service Result view.
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 debug session
or to populate the pipeline during a debugging session.

When you run a service, you can select the launch configuration that Designer uses to
runt the service. If a launch configuration does not exist for a service, Designer creates a
launch configuration and immediately prompts you for input values and then runs the
service. Designer saves the launch configuration in your workspace.
Note: If a service expects an XML document as input, you must create a launch
configuration and debug the service.
To run a service
1 In Package Navigator view, select the service you want to run.
2 In Designer
Run > Run As > Run Service
3 If multiple launch configurations exist for the service, use the Select Launch
Configuration dialog box to select the launch configuration that you want Designer to
use to run the service.
4 If the launch configuration is set up to prompt the user for input values or there is no
launch configuration, in the Enter Input for serviceName dialog box, specify input values
for the service. Click OK. For more information about supplying input values, see
“Entering Input for a Service” on page 232.
Designer runs the service and displays the results in the Service Result view. If the
launch configuration specifies an XML file to use as input, Designer submits the file
to the server, which parses it into a node object and then passes it to the selected
service.
Related Topics
About Debugging Flow Services

When you debug a flow service, Designer provides tools that you can use to monitor the
execution path of the flow service and examine the service pipeline at various points
during service execution. While debugging, you can also use Designer to save or modify
the current pipeline.
Related Topics
 “About Debug Sessions” on page 237
 “About Debug Perspective” on page 238

 “About Debug View” on page 239
About Debug Sessions

A debug session starts when you use a launch configuration to debug a service. Designer
requires a launch configuration for debugging a service. If a service does not have a
launch configuration, Designer creates one automatically. Designer saves the launch
configuration to your workspace.
Designer creates a debug session for each launch configuration that you use for
debugging a service. You can use multiple launch configurations simultaneously and
have multiple debug sessions for the same launch configuration. This translates to
multiple debug sessions for the same service. Debug view displays all of the debug
sessions. The name of the launch configuration used for a debug session appears as a top
level node in the Debug view. The launch configuration can appear in the Debug view
multiple times, once for each debug session.
Once started, debug sessions can suspend, resume, or terminate.
A debug session suspends for the following reasons:
 The launch configuration specifies that the debug session should stop at the first flow
step.
 A step command finishes executing (Step Over, Step Into, or Step Return). Designer
suspends the debug session immediately before executing the next step in the flow
service.
 A breakpoint is encountered.
A debug session resumes when you select Run > Resume or execute a step command.
A debug session terminates for the following reasons:
 The flow service that you are debugging executes to completion (error or success).
 You select the Step Over command for the last step in the flow service.
 You forcefully terminate the debug session by selecting Run > Terminate.
 You exit Eclipse.
Related Topics

About Debug Perspective

When you debug a service, use the Debug perspective. The Debug perspective contains
various views for helping you debug your service. The following table briefly describes
the views available in the Debug perspective. With the exception of Service Result view,
these views are part of the Eclipse Debugging framework.
View Description
Debug view Displays the debug sessions and contains tools to
manage the debugging. When debugging a service in
Designer, the Debug view displays the stack frames
associated with each launch configuration. Debug view
contains commands to start, stop, and step through a
service.
Breakpoints view Displays all the breakpoints currently set in your
workspace.
Service Result view Displays the results of running or debugging a service
via a launch configuration in Designer.
Variables view Displays information about the set of variables for the
selected stack frame in Debug view. When using
Designer to debug a service, Variables view displays the
contents of the pipeline prior to the execution of the
flow step in the selected stack frame in Debug view. The
details pane in Variables view displays detailed
information about the selected variable. You can edit the
variable value in the detail pane. You can save or modify
the contents of Variables view before resuming
execution. Variables view will be blank after the service
executes to completion.
Related Topics

About Debug View

When debugging a service, Designer displays the debugging progress and the flow
service editor (including the flow step that is about to be executed) in Debug view. Keep
the following information in mind when looking at Debug view while debugging a flow
service:
 For each launch configuration that you use to debug a service, Debug view contains a
launch configuration stack frame.
 The launch configuration stack frame contains an Integration Server thread stack
frame. The launch configuration can appear in the Debug view multiple times, once
for each debug session.
 The Integration Server server thread stack frame contains the service thread stack
frame.
 If a debug session is suspended, the service thread stack frame displays
“(suspended)” after the service name.
 The service thread stack frame contains the name of the name of the flow service and
the step at which the debug session is suspended.
 If you stepped into a child INVOKE service or into a transformer in a MAP step,
Debug view displays the parent service (and its flow step) and the child service (and
its flow step) under the service thread stack frame. Designer displays the child service
above the parent service because the child service is at the top of the call stack
structure. Designer highlights the child step at which the debug session is suspended.
Variables view displays the contents of the pipeline that will be passed to the child
service.
 If you stepped into a MAP step to invoke a transformer, under the service thread
stack frame, Designer displays MAPINVOKE before Designer executes the
transformer. Designer displays MAPCOPY right after the service executes but before
Designer executes the links from the transformer to the variables in Pipeline Out.
Debug view with three debug sessions
This debug session

suspended at an INVOKE
step.
This debug session is

suspended at the
parentService.
This debug session stepped

into the childService and
suspended.

Related Topics
Debugging a Flow Service

While debugging a service, you can:
 Execute a flow service one flow step at a time and view the results of each step.
 Set breakpoints to specify points in a flow service at which processing should stop.
 Change the values passed to each step in the flow service.
Use the following procedure to debug a flow service.
To debug a flow service
1 In Package Navigator view, select the service you want to debug.
2 In Designer
Run > Debug As > Debug Flow Service
3 If multiple launch configurations exist for the service, use the Select Launch
Configuration dialog box to select the launch configuration that you want Designer to
use to debug the service.
4 If the launch configuration is set up to prompt the user for input values or there is no
launch configuration, in the Enter Input for serviceName dialog box, specify input values
for the service. Click OK. For more information about supplying input values, see
“Entering Input for a Service” on page 232.
Designer does one of the following:
 If the launch configuration specifies that execution should stop at the first flow
step when debugging, Designer prompts you to switch to the Debug perspective.
Designer suspends flow service execution immediately before executing the first
flow step. For more information about stepping through a flow service, see
“Stepping Through Flow Services” on page 241.
 If you are not using an existing launch configuration to debug the service (that is,
Designer created one for you automatically), Designer suspends flow service
execution immediately before executing the first flow step.

 If the launch configuration does not stop a the first flow step, Designer executes
the flow service until a breakpoint hit occurs. Designer prompts you to switch to
the Debug perspective. To resume service execution after Designer encounters a
breakpoint, select Run > Resume.
 If the flow service does not stop at the first flow step and does not contain a
breakpoint, Designer executes the flow service to completion.
Related Topics
 “Disabling Flow Steps, Transformers, and Conditions” on page 249
Stepping Through Flow Services

You use the Step Over, Step Into, and Step Out commands during a debug session 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 Step Over

Open a child flow a 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 Return
Related Topics
 “Stepping Through a Flow Service” on page 242
 “Stepping Into and Out of a Child Service” on page 242
 “Stepping Into and Out of a MAP Step” on page 243

Stepping Through a Flow Service

When stepping through a flow service, keep the following points in mind:
 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.
 If the debug launch configuration is not configured to stop at the first flow step or
there is not an enabled breakpoint in the flow service or one of its child services,
Designer will execute the service to completion and will not suspend at any flow step.
 When you step through a flow step, Designer executes the step and then suspends the
debug session.
 The Variables view displays the pipeline that will be passed to the next step in the
flow service. You can modify, save, or restore the data while debugging the service.
 If you step over a flow step that contains an enabled breakpoint, Designer suspends
service execution at the breakpoint.
To step through a flow service
1 Debug the service as described in “About Debugging Flow Services” on page 236.
2 In Debug view, select the flow step in the debug session for the service that you want
to step through.
3 In Designer, select Run > Step Over or click on the Debug view toolbar.

Designer executes the current step and then stops.
Related Topics
Stepping Into and Out of a Child Service

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 Return commands.
To step into and out of a child flow
2 In Debug view, step to the flow step that invokes the child flow service.

3 In Designer, select Run > Step Into or click on the Debug view toolbar.

Designer opens the child flow service and selects (but does not execute) the first step.
4 To execute the first step in the child flow service, select Run > Step Over or click on

the Debug view toolbar. Repeat this step for each flow step that you want to
individually execute within the child flow service.
5 If you want to return to the parent flow service without stepping through the entire
child, select Run > Step Return or click on the Debug view toolbar. Designer
executes the remaining steps in the child flow service, returns to the parent, and then
selects (but does not execute) the next step in the parent flow.
Notes:
 If you select Step Over 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 Return without executing the entire child flow service and the child
flow service subsequently contains an enabled breakpoint, Designer stops debugging
when it hits the breakpoint.
Related Topics
Stepping Into and Out of a MAP Step

You can use the step commands to debug individual transformers within a MAP step.
To step into and out of a MAP step
2 In Debug view, step to the MAP flow step.
3 In Designer, select Run > Step Into or click on the Debug view toolbar.

In Pipeline view, Designer highlights the links to the transformer (but does not
execute) a transformer in the MAP step. Keep in mind that transformers in a MAP
step are independent of each other and do not execute in a specific order.

4 If the transformer is a flow service and you want to step into the transformer, do the
following:
a Select Run > Step Into or click on the Debug view toolbar. Designer executes the

links to the transformer and steps into the transformer (flow service). Continue
stepping through the transformer using Step INto or Step Over.
To return to the MAP step pipeline, select Run > Step Return or click on the

Debug view toolbar.
b Select Run > Step Over or click to execute the links between the transformer to

the variables in Pipeline Out.
c Repeat steps a–b for each transformer that you want to individually execute in the
MAP step. If you want to execute the next transformer without stepping through
transformer and link execution, select Run > Step Over.
5 If the transformer is not a flow service or you do not want to step into it, select Run >
Step Over or click on the Debug view toolbar.
6 If you want to return to the parent without stepping through the entire MAP, select
Run > Step Return or click on the Debug view toolbar. This executes the remaining
transformers in the MAP, returns to the parent flow service, and selects (but does not
execute) the next step in the parent flow service.
Notes:
 If you select Step Return, Designer executes the remaining steps in the MAP and
returns to the parent automatically. However, Designer stops executing if it
encounters an enabled breakpoint.
 You can use Step Into to step into a transformer that is not a flow service.
 In Debug view, under the service thread stack frame, Designer displays
MAPINVOKE before Designer executes the transformer. Designer displays
MAPCOPY right after the service executes but before Designer executes the links
from the transformer to the variables in Pipeline Out.
Related Topics

Using Breakpoints
Within Designer, a breakpoint is a point in a flow service where you want processing to
halt when you debug that flow service. 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 in the Variables view before and after that segment
executes.
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 the debug session suspends. To resume
processing, you can execute one of the step commands or select Run > Resume. After you
resume the debug session, Designer stops at any subsequent breakpoints.
When working with breakpoints, keep the following points in mind:
 Breakpoints are persistent in Designer.
 Breakpoints are also local to your Designer workspace. Breakpoints that you set in
your workspace 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 in debug session.
Breakpoints are ignored when you run a service.
 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.
 When you delete a flow step or transformer that contains a breakpoint, Designer
removes the breakpoint.
 You can use breakpoints as markers in your flow services. To do this, assign a
breakpoint to the flow step that you want to use as a marker. In Breakpoints view,
you can quickly go to the flow step by right‐clicking the breakpoint and selecting Go
to File or by double‐clicking the breakpoint.
 You can use Breakpoints view to manage your existing breakpoints.
Related Topics
 “Breakpoint States” on page 246
 “Setting and Removing Breakpoints” on page 246
 “Enabling and Disabling Breakpoints” on page 248
 “Skipping Breakpoints” on page 248

Breakpoint States
Breakpoints can have the following states.
Icon State Description

Enabled/Non‐Execution The breakpoint is enabled, but there is no debug
session in progress.
Disabled/Non‐Execution The breakpoint is disabled and there is no debug
session in progress.
Skip/Enabled Indicates the breakpoint is enabled but will be
skipped.
Skip/Disabled Indicates the breakpoint is disabled and will be
skipped.
Setting and Removing Breakpoints

When you set a breakpoint, you select the flow service step or transformer that will host
the breakpoint. During debugging, processing will halt immediately before this flow step
or transformer.
Related Topics
 “Setting and Removing Breakpoints on Flow Step” on page 246
 “Setting or Removing Breakpoints on a Transformer” on page 247
Setting and Removing Breakpoints on Flow Step

You can set or remove a breakpoint on a flow step by toggling the breakpoint.
To toggle a breakpoint on a flow step
 Open the flow service in which you want to set a breakpoint and do one of the
following:
 On the Tree tab, right‐click the step at which you want to set the breakpoint and
select Toggle Breakpoint. Designer displays or removes in the vertical margin
next to the flow step.

 On the Tree tab, right‐click in the vertical margin next to the flow step at which
you want to set a breakpoint and select Toggle Breakpoint. Alternatively, double‐
click in the margin next to the flow step. Designer displays or removes in the
vertical margin next to the flow step.
 On the Layout tab, double‐click the connection line in front of the flow step at
which you want to set a breakpoint and select Toggle Breakpoint. Designer displays
or removes right before the flow step.
 On the Layout tab, select the connection line in front of the flow step at which you
want to set a breakpoint. Right‐click and select Toggle Breakpoint. Designer
displays or removes right before the flow step.
Note: You can also use Breakpoints view to remove breakpoints or select Run > Remove

All Breakpoints.
Related Topics
Setting or Removing Breakpoints on a Transformer

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.
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
Designer reaches the breakpoint, even if the transformers appear below the breakpoint in
the Pipeline view. Likewise, transformers above the breakpoint might not execute before
the breakpoint is encountered and the debug session suspends. These will execute when
the debug session resumes.
You set or remove a breakpoint on a transformer by toggling the breakpoint state.
To toggle 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 In Pipeline view, right‐click the name of the transformer that will function as the
breakpoint and select Toggle Breakpoint. Designer displays or removes next to the
transformer name.
Related Topics
Enabling and Disabling Breakpoints

You can enable or disable a breakpoint to instruct Designer to stop at or ignore the
breakpoint.
To enable or disable a breakpoint on a flow step or transformer
1 Open the flow service and navigate to the breakpoint. If a breakpoint is set on a
transformer, select the MAP step and open Pipeline view.
 To disable a breakpoint, right‐click the breakpoint and select Disable Breakpoint.
 To enable a breakpoint, right‐click the breakpoint and select Enable Breakpoint.
Note: You can also enable and disable breakpoints using Breakpoints view.
Related Topics
Skipping Breakpoints
You can use Designer to change the breakpoint state of all breakpoints to “skip”.
Designer does not execute breakpoints with a skip state regardless of whether the
breakpoint is enabled or disabled. Designer debugs services as if the breakpoints did not

exist or were disabled. By instructing Designer to skip all breakpoints, you can debug the
service without halting execution for a breakpoint without removing or changing the
enabled/disabled state of the breakpoint.
To skip all breakpoints
 In Designer
Run > Skip All Breakpoints
Related Topics
Disabling Flow Steps, Transformers, and Conditions

As part of debugging services, you can disable flow steps and transformers. You can also
disable conditions placed on the links between variables in the pipeline. Disabled flow
steps and transformers do not execute. When a condition is disabled, the condition is
ignored and the link between the variables executes.
Related Topics
 “Disabling and Enabling Flow Steps and Transformers” on page 249
Disabling and Enabling Flow Steps and Transformers

Disabling a step or transformer is useful in many 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
debugging.
Keep the following points in mind when disabling and enabling flow steps and
transformers:
 Disabling a step or transformer sets a persistent attribute that is saved in the flow
service. Once you disable a step or transformer, it remains disabled until you
explicitly re‐enable it with Designer.
 Steps and transformers that you disable are not executed at run time.
 The symbol appears next to disabled steps and transformers.

 If you disable a parent step (for example, a LOOP or a BRANCH), Designer disables
its children automatically.
 If you disable a MAP step, Designer disables the transformers in the MAP step
automatically.
 Disabling a step or transformer removes a breakpoint hosted by that step or
transformer.
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 or transformer can break the logic
of a service and/or cause the service to fail. Designer allows you to disable any step or
transformer in a flow service, but it is your responsibility to use this feature carefully.
To disable or enable a flow step or transformer
1 Open the flow service that you want to edit.
 In the editor select the step that you want disable or enable.
 In the editor select the MAP step containing transformers that you want to disable
or enable.
3 Right‐click the step or transformer and do one of the following:
 Select Disable Step to disable the step or transformer.
 Select Enable Step to re‐enable the step or transformer.
Related Topics
Disabling and Enabling Conditions

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 debugging, you might want to disable
or remove the condition from the link to make sure that Designer properly copies data
between variables. By disabling the condition, you instruct Designer to ignore the
condition placed on the link and automatically execute the link.
Disabling the condition preserves the written expression. When you enable the condition,
you do not need to rewrite the expression.

The Pipeline view uses a blue link (line) to indicate that properties (such as conditions
and array indexes) have been applied to the link between variables. Designer retains the
blue color even when you disable the applied condition to remind you that properties
have been set.
To disable or enable a condition placed on a link between variables
1 Open the flow service that you want to edit.
2 In the editor, select the INVOKE or MAP step that contains the link with the
condition you want to disable or enable.
3 In the Pipeline view, select the link with the condition that you want to disable.
4 In the General category of the Properties view, do one of the following:
 To disable the condition, set the Evaluate copy condition property to False.
 To re‐enable the condition, set the Evaluate copy condition property to True.
Related Topics
 “Disabling and Enabling Flow Steps and Transformers” on page 249
Modifying the Pipeline while Debugging

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 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. You cannot modify the values of the pipeline after
the service ends. However, if you debug the service using the step commands, you
can modify the pipeline values for the next flow 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 can load an entirely different pipeline for Designer to pass to the next step in the
flow service.
 You can save the contents of the pipeline to a file. You may want to save the results of
specific flow steps to a file to compare with other services or to use in later debug
sessions.
Related Topics
 “Changing Variable Values” on page 252
 “Dropping Variables” on page 253
 “Restoring the Pipeline while Debugging” on page 256
Changing Variable Values

Keep the following points in mind when changing the values of variables while
debugging the service:
 When you modify values in the pipeline, the changes only apply to the current
debugging session. Neither the service nor launch configuration is permanently
changed.
 You can only modify existing variables. You cannot add new variables to the pipeline.
 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.
 Variables that contain com.wm.util.Table objects appear as document lists in Variables
view.
 You can edit rows and columns for String Table and Document List variables.
 You can replace the value of all the variables by loading a saved pipeline from a file.
 You can use the step tools to step to the location in the service at which you want to
change the pipeline. You can also set a breakpoint on the flow step at which you want
to change the pipeline values.
 You can only change the pipeline for the top‐most stack frame in the debug session.

To change the value of variable while debugging
2 In the debug session, use the step command or a breakpoint to reach the step for
which you want to change variable values in the flow service.
3 In Variables view, right‐click the variable whose value you want to change and select
Change Value.
4 In the Input dialog box, enter a new value for the variable. Click OK.
5 Continue debugging the service using the step commands or selecting Run > Resume.
Note: You can also change a variable value by selecting the variable and then
modifying the value in the detail pane.
Related Topics
 “Dropping Variables” on page 253
Dropping Variables
When dropping variables from the pipeline while debugging the service, keep the
 You can only modify the pipeline when a subsequent step in the service exists to
which to pass the pipeline values. You cannot modify the values of the pipeline after
the service ends. However, if you debug the service using the step commands, you
can modify the pipeline values for the next flow step in the service.
 When drop variables from the pipeline, the changes only apply to the current
debugging session. The service is not permanently changed.
 You can only drop existing variables. You cannot add new variables to the pipeline.
 You can only change the pipeline for the top‐most stack frame in the debug session.
To drop values from the pipeline while debugging
which you want to drop a pipeline variable.

3 In Variables view, select the variable you want to drop from the pipeline and click
on the Variables view toolbar. Designer removes the variable from Variables view.
Related Topics
 “Changing Variable Values” on page 252
Saving and Restoring the Pipeline while Debugging

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.
Related Topics
Saving the Pipeline while Debugging

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 debug another service
against the current set of pipeline values or if you want to restore the pipeline to this
exact state later in the debugging process. There are two ways to save the contents of the
pipeline:
 You can manually save the contents when you debug a service using Designer.
 You can programmatically save the pipeline at run time by invoking
pub.flow:savePipelineToFile at the point where you want to capture the pipeline. For more
information about using this service, see webMethods Integration Server Built‐In Services
Reference.

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 Variables view while debugging a service.
 Load a default set of input values when creating a launch configuration.
 Load a set of input values into the Input dialog box when debugging a service with
Designer.
 Dynamically load the pipeline at run time using the pub.flow:restorePipelineFromFile
service.
Related Topics
 “Saving the Pipeline to a File while Debugging” on page 255
 “Loading a Saved Pipeline” on page 256
Saving the Pipeline to a File while Debugging

When saving the pipeline during a debugging session, 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.
To save the pipeline to a file while debugging
which you want to save the pipeline.
 To save the pipeline to your local file system, click on the Variables view
toolbar. Specify a location and name for the file in the Save As dialog box. Click
Save.
 To save the pipeline to the IntegrationServer_directory\pipeline directory on the
machine on which Integration Server reside, click on the Variables view
toolbar. In the Save Pipeline to serverName dialog box, specify the name for the file
containing the pipeline contents.

Related Topics
Restoring the Pipeline while Debugging

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 debugging situations. For example, you can use it to replace the
existing pipeline with a different set of values when stepping though a flow service with
the debugging tools.
There are two ways to restore the contents of the pipeline:
 You can manually load the saved pipeline into the Variables view while debugging in
Designer.
 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. For
more information about using this service, see webMethods Integration Server Built‐In
Services Reference.
Related Topics
Loading a Saved Pipeline

When you load a pipeline file into Variables view, the contents of the pipeline file
completely replaces the current pipeline. Designer passes the new set of values to the next
step. 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.”
To load a pipeline file into Variables view while debugging
which you want to load the saved pipeline.

 To load the pipeline from your local file system, click on the Variables view
toolbar. In the Open dialog box, navigate to and select the file. Click Open.
 To load the pipeline from the IntegrationServer_directory\pipeline directory on the
machine on which Integration Server reside, click on the Variables view
toolbar. In the Load IData from Server dialog box, specify the name for the file
containing the pipeline contents.
Related Topics
Viewing Service Results

When you execute a service by running or debugging it, Designer displays the results in
Service Result view. Designer creates a Service Result view for each launch configuration.
Important! If you use a launch configuration to debug a service and then later use the
same launch configuration, Designer uses one Service Result view for both executions
of the launch configuration. The results of the second launch configuration to
complete will overwrite the results of the first launch configuration.
Service Result view can contain up to three tabs:
 Messages tab displays any messages from Designer about the launch configuration
and any exceptions thrown by the service during execution.
 Call Stack tab identifies the flow step that generated the error and lists its antecedents.
 Pipeline tab displays the contents of the pipeline at the time the service finished
executing.
Related Topics
 “Messages Tab” on page 258
 “Call Stack Tab” on page 258
 “Pipeline Tab” on page 259

 “Restoring the Service Results” on page 261
Messages Tab
The Messages tab in the Service Result view displays the time the launch configuration
started and completed executing, the name and location of the launch configuration, and
any error and exception messages generated by Integration Server during service
execution. If you did not use a launch configuration when running or debugging the
service, Designer displays the name and location of the launch configuration it created to
execute the service.
Related Topics
Call Stack Tab

The Call Stack tab identifies which service generated the error and lists its antecedents.
Call Stack also identifies the flow step that executed when the error occurred. Service
Result view contains a Call Stack tab only if the service throws an exception.
Keep the following points in mind when looking at the Call Stack tab.
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 Designer). If the parent itself throws the exception, it will be
the only entry in the call stack.
You can go to the flow step that was execution when the error occurred by clicking on
the Service Result view. To view the service in Package Navigator view, right‐click the
service and select Show In > Navigator.
Related Topics

Pipeline Tab
The Pipeline tab in Service Result view contains the contents of the pipeline after the
service finishes executing.
Keep the following points in mind when examining the Pipeline tab in Service Result
view.
 The Pipeline tab 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
Pipeline tab.
 When you select a variable in the Pipeline tab, Designer displays details about the
variable value in the details panel in the lower half of the Pipeline tab. For array
variables, Designer displays the index number and position for each item in the array.
You can copy and paste values from the details panel in the Pipeline tab.
 You can browse the contents of the Pipeline tab, but you cannot edit it directly.
However, you can edit the contents of the pipeline while debugging a service. For
more information, see “Modifying the Pipeline while Debugging” on page 251.
 You can save the contents of the Pipeline tab 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 Pipeline tab in the Service Result view, see “Saving the Service
Results” on page 260 and “Restoring the Service Results” on page 261.
 When a failure occurs within a Java service, the Pipeline tab represents the state of the
pipeline at the point when that Java service was initially called. If the Java service
made changes to these values before throwing the exception, those changes will note
be reflected on the Pipeline tab.
 If you run a service and an error occurs, results are not displayed in the Pipeline tab.
 Variables whose object types are not directly supported by Designer will appear in
the Pipeline tab, but because Designer 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 Pipeline
tab.

Related Topics
Saving the Service Results

You can save the service results pipeline to a file. You might do this so that you can
compare saved service result pipelines to each other.
When you save a pipeline, it is saved in a file in XML format. The file you create can be
used to:
 Dynamically load the pipeline at run time using the pub.flow:restorePipelineFromFile
service.
 Load a set of input values when creating a launch configuration or when running or
debugging a service.
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.
Use the following procedure to save the service results pipeline to a pipeline file.

To save the service results pipeline
 On the Pipeline tab in Service Result view, do one of the following:
Click... To...
Save the pipeline to your local file system.
Specify a location and name for the file in the Save As dialog box.
Click Save.
Save the pipeline to IntegrationServer_directory\pipeline
directory on the machine on which Integration Server resides.
In the Save Pipeline to serverName dialog box, specify the name for
the file containing the pipeline contents.
Related Topics
Restoring the Service Results

When you load a pipeline file into the Pipeline tab in Service Result view, the contents of
the pipeline file completely replaces the service results pipeline.
To restore service results
 On the Pipeline tab in Service Result view, do one of the following:
Click... To...
Restore the pipeline from a file in your local file system.
In the Open dialog box, navigate to and select the file. Click Open.
To restore the pipeline from the
IntegrationServer_directory\pipeline directory on the machine on
which Integration Server resides.
In the Restore Pipeline from serverName dialog box, specify the
name for the file containing the pipeline contents.

Related Topics

11 Working With Document Types
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.
Related Topics
 “Creating a Document Type” on page 263
 “Working with Publishable Document Types” on page 272
 “Editing Document Types” on page 285
 “Synchronizing Publishable Document Types” on page 287
 “Testing Publishable Document Types” on page 295
 “About Universal Names and Document Types” on page 299
Creating a Document Type

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.

Note: In webMethods Developer, you could create a document type from a Broker
document type. This functionality is not available in Designer. If you want to create a
document type, specifically a publishable document type, from a Broker document
type, use webMethods Developer.
Related Topics
 “Creating an Empty IS Document Type” on page 264
 “Creating an IS Document Type from an XML Document, DTD, or XML Schema” on
page 265
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.
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
1 In Designer
File > New > Document Type
2 In the New Document Type dialog box, select the folder in which you want to save
the IS document type.
3 In the Element 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 34.
4 Click Finish.
Integration Server generates an IS document type and Designer displays it in the
Related Topics
 “Adding Fields to an IS Document Type” on page 265

Adding Fields to an IS Document Type
To add fields to the IS document type
1 In Package Navigator view, double‐click the document type to which you want to
add fields.
The document type opens in the Document Type Editor window.
2 Drag the document type field that you want to define from the Palette to the
document type tab in the editor.
3 Type the name of the field and then press ENTER.
Note: Designer prevents the insertion of fields named _env in an IS document
type. For details about the _env field, see “About the Envelope Field” on
page 277.
4 With the field selected, set field properties and apply constraints in the Properties
view (optional).
5 If the field is a document or a document list, repeat steps 2–4 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.
6 Select File > Save.
Note: Designer displays small symbols next to a field icon to indicate validation
constraints. Designer uses to indicate an optional field. Designer 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 304.
Related Topics
 “Applying Constraints to Variables” on page 304
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. Keep the following points in mind
when creating an IS document type from a source file.
 When you base the IS document type on a source file, Integration Server 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.
 When creating a field from an attribute declaration, 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.
Related Topics
 “Creating an IS Document Type from an XML Document” on page 266
 “Creating an IS Document Type from a DTD” on page 267
 “Creating an IS Document Type from an XML Schema” on page 268
Creating an IS Document Type from an XML Document

You can create an IS document type that matches the structure and fields in an XML
document.
To create an IS document type from an XML document
1 In Designer
4 Click Next.
5 Under Select a source, select XML.
6 In the Enter the URL or select a local file box, do one of the following:
 If you want to base the IS document type on a file that resides on the Internet,
type the URL of the resource. (The URL you specify must begin with http: or
https:.)
 If you want to base the IS document type on a file that resides on your local file
system, type in the path and file name, or click the browse button to navigate to
and select the file.

7 Click Finish. Integration Server generates the IS document type using the XML
document you specified and Designer displays it in the Package Navigator view.
The IS document type is saved on Integration Server. If you want to add or edit fields
in the IS document type, see “Creating an Empty IS Document Type” on page 264.
Related Topics
page 265
Creating an IS Document Type from a DTD

When creating an IS document type from a DTD, keep in mind that 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" ?>
To create an IS document type from a DTD
1 In Designer
4 Click Next.
5 Under Select a source, select DTD.
https:.)
7 Click Next.

8 Select the root element of the document.
9 Click Finish. Integration Server generates the IS document type and IS schema and
saves it on the server. Designer displays them in the Package Navigator view.
If you want to add or edit fields in the IS document type, see “Creating an Empty IS
Document Type” on page 264.
Note: You might receive errors or warnings when creating an IS document type
from a DTD definition. For more information about these errors and warnings,
Related Topics
page 265
Creating an IS Document Type from an XML Schema

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, Designer displays an error
message that lists the number, title, location, and description of the validation errors
within the XML Schema.
 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”
 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 270.
 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 272.

To create an IS document type from an XML Schema
1 In Designer
4 Click Next.
5 Under Select a source, select XML Schema.
https:.)
7 Click Next.
8 Select the root element of the document.
9 Select the appropriate option to specify whether Designer should process complex
types by expanding them inline in the editor or by generating them as separate IS
document types.
10 Click Finish. Integration Server generates the IS document type(s) and IS schema and
saves it on the server. Designer displays them in the Package Navigator view.
If you want to add or edit fields in the IS document type, see “Creating an Empty IS
Note: You might receive errors or warnings when creating an IS document type
from an XML Schema definition. For more information about these errors and
warnings, see the webMethods Developer User’s Guide.
Related Topics
 “Expanding Complex Document Types Inline” on page 270
 “Generating Fields for Substitution Groups” on page 272
page 265

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, Integration Server does not include that
element in the IS document type.
Working with Publishable Document Types

A publishable document type is a named schema‐like definition that describes the
structure and publication properties of a particular kind of document. Essentially, a
publishable document type is an IS document type with specified publication properties
such as storage type and time‐to‐live.
In an integration solution that uses the publish‐and‐subscribe model, services publish
instances of publishable document types, and triggers subscribe to publishable document
types. A trigger specifies a service that the Integration Server invokes to process the
document. For example, you might create a publishable document type named EmpRec
that describes the layout of an employee record. You might create a trigger that specifies
that the Integration Server should invoke the addEmployeeRecord service when instances of
the EmpRec are received. When a service or adapter notification publishes a document of
type EmpRec, that document would be queued for the subscribers of document type
EmpRec. The Integration Server would pass the document to and invoke the
addEmployeeRecord service.
In a publication environment that includes a Broker, each publishable document type is
associated with a Broker document type. Designer provides tools that you can use to
ensure that these two document types remain synchronized.
When you build an integration solution that uses publication and subscription, you need
to create the publishable document types before you create triggers, services that process
documents, and services that publish documents.
Related Topics
 “Creating a Publishable Document Type” on page 273
 “Specifying Document Storage Type” on page 280
 “Specifying the Time to Live for a Publishable Document Type” on page 282
 “Specifying Validation for a Publishable Document Type” on page 283

Creating a Publishable Document Type

To create a publishable document type, you make an IS document type publishable by
setting publication properties for the document type. Properties that you can set include:
specifying whether instances of the publishable document type should be saved in
memory (volatile storage) or saved on disk (guaranteed storage) during processing, and
specifying how long instances of the publishable document type should remain on the
Broker once they are published.
If the Integration Server on which you have a session is connected to a Broker, when you
make an IS document type publishable, Integration Server automatically creates a Broker
document type. Integration Server automatically assigns the Broker document type a
name. This name corresponds to the following format:
wm::is::folderName::documentTypeName. If a document type with this name already exists on
the Broker, the Integration Server appends “_1” to the Broker document type name.
For example, if you make the IS document type employee.employeeInfo publishable, the
Integration Server creates the Broker document type wm::is::employee::employeeInfo.
However, if a developer using another Integration Server created a Broker document
type for an identically named IS document type, the Integration Server assigns the new
Broker document type the name wm::is::employee::employeeInfo_1.
If the Integration Server on which you have a session is not connected to a Broker, the
publishable document types that you create can be used only in local publishes. That is,
instances of the publishable document types can only be published and subscribed to
with in the same Integration Server. (Local publishes do not involve a Broker.) Later,
when Integration Server is connected to a Broker, you can create a Broker document type
for the publishable document type by pushing the document type to the Broker during
synchronization.
Related Topics
 “Making a Document Type Publishable” on page 273
 “About the Associated Broker Document Type Name” on page 275
 “About the Envelope Field” on page 277
 “About Adapter Notifications and Publishable Document Types” on page 278
 “Making Document Types Unpublishable” on page 279
Making a Document Type Publishable

Keep the following points in mind when making a document type publishable:
 You can only make an IS document type publishable if you own the lock on the IS
document type (or you have it checked out) and you have write permission to the IS
document type.
 If you want to generate an associated Broker document type at the same time you
make the IS document type publishable, make sure that a Broker is configured and
the Integration Server on which you are working is connected to it.

 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. For more information about
the _env field, see “About the Envelope Field” on page 277.
 The Broker prohibits the use of certain field names, for example, Java keywords, @, *,
and names containing white spaces or punctuation. If you make a document type
publishable and it contains a field name that is not valid on the Broker, you cannot
access and view the field via any Broker tool. However, the Broker transports the
contents of the field, which means that any other Integration Server connected to that
Broker has access to the field as it was displayed and implemented on the original
Integration Server. Use field names that are acceptable to the Broker. See the
webMethods Broker Administrator’s Guide for information on naming conventions for
Broker elements.
To make a document type publishable
1 In the Package Navigator of Designer, double‐click the document type that you want
to make publishable.
2 In the Properties view, set the Publishable property to True.
3 Next to the Discard property, select one of the following to indicate how long
instances of this publishable document type remain in the trigger client queue before
the Broker discards them.
Select... To...
False Specify that the Broker should never discard instances of this
publishable document type.
True Specify that the Broker should discard instances of this
publishable document type after the specified time elapses.
In the fields next to Time to live specify the time‐to‐live value and
time units.
4 Next to the Storage type property, select the storage method to use for instances of this
Select... To...
Volatile Specify that instances of this publishable document type are
volatile. Volatile documents are stored in memory.
Guaranteed Specify that instances of this publishable document type are
guaranteed. Guaranteed documents are stored on disk.
For more information about selecting a storage type, see “Selecting Document
Storage Type for a Publishable Document Type” on page 281.

5 Select File > Save. Designer displays beside the document type name in the

Package Navigator to indicate it is a publishable document type.
Notes:
 In the Properties view, the Broker doc type property displays the name of the
corresponding document type created on the Broker. Or, if you are not connected to a
Broker, this field displays “Publishable Locally Only”. (Later, when the Integration
Server is connected to a Broker, you can create a Broker document type for this
publishable document type by pushing the document type to the Broker during
synchronization.) You cannot edit the contents of this property. For more information
about the contents of this property, see “About the Associated Broker Document Type
Name” on page 275.
 When you make a document type publishable, the Integration Server adds an
envelope field (_env) to the document type automatically. When a document is
published, the Integration Server and the Broker populate this field with metadata
about the document. For more information about this field, see “About the Envelope
Field” on page 277.
6 Once a publishable document type corresponds to 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 “Synchronizing Publishable Document
Types” on page 287.
About the Associated Broker Document Type Name

For a document type, the contents of the Broker doc type property can indicate the
following:
 Whether or not the document type is publishable.
 Whether the publishable document type was created from a Broker document type
that was itself created from an IS document type.
 Whether the publishable document type was created from a Broker document type
created in an earlier version of a webMethods component.
 Whether instances of the publishable document type can be used in local publishes
only. If the publishable document type can be used only in local publishes, there is no
corresponding Broker document type.
The following table lists and describes the possible contents of the Broker doc type
property.

Broker doc type property Description

wm::is::folderName::documentTypeName The name of the Broker document type that
corresponds to the publishable document type.
The wm::is prefix indicates that the Broker
document type was created from an IS document
type. (Either the current document type or an IS
document type created and made publishable on
another Integration Server.) This prefix does not
specify which Integration Server the source IS
document type is located on.
On the Broker, all document types created from
an IS document type are located in the is folder,
which is a subfolder of the wm folder. The
folderName::documentTypeName portion of the name
further identifies where the document type is
located on the Broker.
Example:
wm::is::customerSync::Customer::updateCustomer
Indicates the Broker document type
updateCustomer is located in the following series of
folders wm::is::customerSync::Customer.
folderName::documentTypeName The name of the Broker document type that
corresponds to the publishable document type.
The absence of the wm::is prefix indicates that the
publishable document type was generated from a
Broker document type created with an earlier
version of a webMethods component.
Example:
Customer::getCustomer
Indicates the Broker document type getCustomer is
located in the Customer:: folder.

Broker doc type property Description

Publishable Locally Only Indicates that instances of the publishable
document type can be used in local publishes
only. This publishable document type does not
have a corresponding Broker document type.
When you made this document type publishable,
Integration Server was not connected to a Broker.
See the webMethods Integration Server
Administrator’s Guide for information about
connecting the Integration Server to the Broker.
Note: If you want instances of this publishable
document type to be published to the Broker, you
need to create a Broker document type for this
publishable document type. When the Integration
Server is connected to a Broker, you can create the
Broker document type by pushing the
publishable document type to the Broker during
synchronization. For more information about
synchronizing, see “Synchronizing Publishable
Document Types” on page 287.
Not Publishable Indicates that this IS document type is not

publishable. For information about making an IS
document type publishable, see “Making
Document Types Unpublishable” on page 279.
About 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. The envelope is much like a header in
an email message. The pub:publish:envelope document type defines the content and
structure of the envelope that accompanies the published 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.
Because the _env field is needed for publication, Designer controls the usage of the _env
field in the following ways:
 You cannot insert an _env field in a document type. Designer automatically inserts the
_env field as the last field in 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 and paste this field to the Input/Output tab or into a specification.

 You cannot move, rename, cut, or delete the _env field from a document type.
Designer automatically removes the _env field when you make a document type
unpublishable.
 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 webMethods Integration Server Built‐In Services Reference.
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.
About Adapter Notifications and Publishable Document Types

Adapter notifications determine whether an event has occurred on the adapterʹs resource
and then sends the notification data to Integration Server in the form of a published
document. There are two types of adapter notifications: polling notifications, which poll
the resource for events that occur on the resource, and listener notifications, which work
with listeners to detect and process events that occur on the adapter 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 Integration Server.
Each adapter notification has an associated publishable document type . When you
create an adapter notification in Designer, Integration Server automatically generates a
corresponding publishable document type. Designer assigns the publishable document
type the same name as the adapter notification, but appends PublishDocument to the
name. You can use the adapter notification publishable document type in triggers and
flow services just as you would any other publishable document type.
The adapter notification publishable document type is directly tied to its associated
adapter notification. In fact, you can only modify the publishable document type by
modifying the adapter notification. Integration Server automatically propagates the
changes from the adapter notification to the publishable document type. You cannot edit
the adapter notification publishable document type directly.
When working in Package Navigator, Designer treats an adapter notification and its
publishable document type as a single unit. If you perform an action on the adapter
notification Designer performs the same action on the publishable document type. For
example, if you rename the adapter notification, Designer automatically renames the
publishable document type. If you move, cut, copy, or paste the adapter notification
Designer moves, cuts, copies, or pastes the publishable document type.
For information about how to create and modify adapter notifications, see the
appropriate adapter user’s guide.

Making Document Types Unpublishable

You can change any publishable document type to a regular IS document type by making
the publishable document type unpublishable. Keep the following points in mind when
changing the publication status of a publishable document type:
 When you make a document type unpublishable, you can decide whether or not the
associated Broker document type should be deleted. However, the Integration Server
prevents you from deleting the associated Broker document type if a subscription
exists for it.
 Broker/local triggers and publishing services can only use publishable document
types. If you make a publishable document type unpublishable, You can only specify
publishable document types in triggers and in publishing services. When you make a
publishable document type unpublishable, you need to update triggers or publishing
services that used the publishable document type.
 If a publishing service specifies the publishable document type and you make the
document type unpublishable, the publishing service will not execute successfully.
The next time the service executes, Integration Server throws a service exception
stating that the specified document type is not publishable.
 You can only publishable status of an IS document type if you own the lock on the IS
document type (or you have it checked out) and you have write permission to the IS
document type.
To make a publishable document type unpublishable
1 In the Package Navigator of Designer, double‐click the document type that you want
to make unpublishable.
2 In the Properties view, set the Publishable property to False.
4 If the document type is associated with a Broker document type, Designer displays
the Delete Confirmation dialog box. This dialog box prompts you to specify whether
the associated Broker document type should be deleted or retained.
5 If you would like to delete the associated Broker document type from the Broker,
click Yes. Otherwise, click No.

Specifying Document Storage Type

For a publishable document type, you can set the storage type to determine how
Integration Server and Broker store instances of this document. The storage type also
determines how quickly the document moves through the webMethods system. You can
select one of the following storage types:
 Volatile storage specifies that instances of the publishable document type are stored in
memory. Volatile documents move through the webMethods system more quickly
than guaranteed documents because resources do not return acknowledgements for
volatile documents. (An acknowledgement indicates that the receiving resource
successfully stored or processed the document and instructs the sending resource to
remove its copy of the document from storage.) However, if a volatile document is
located on a resource that shuts down, the volatile document is not recovered when
the resource restarts.
Integration Server provides at‐most‐once processing for volatile documents. That is,
document delivery and processing are attempted but not guaranteed for volatile
documents. Integration Server might process multiple instances of a volatile
document, but only if the document was published more than once. Specify volatile
storage for documents that have a short life or are not critical.
 Guaranteed storage specifies that instances of the publishable document type are stored
on disk. Resources return acknowledgements after storing or processing guaranteed
documents. Because guaranteed documents are saved to disk and acknowledged,
guaranteed documents move through the webMethods system more slowly than
volatile documents. However, if a guaranteed document is located on a resource that
shuts down, the resource recovers the guaranteed document upon restart.
webMethods components provide guaranteed document delivery and guaranteed
processing (either at‐least‐once processing or exactly‐once processing) for guaranteed
documents. Guaranteed processing ensures that once a trigger receives the document, it
is processed. Use guaranteed storage for documents that you cannot afford to lose.
Note: Some Broker document types have a storage type of Persistent. The
Persistent storage type automatically maps to the guaranteed storage type in the
Integration Server.
Related Topics
 “Document Storage Versus Client Queue Storage” on page 281
 “Selecting Document Storage Type for a Publishable Document Type” on page 281

Document Storage Versus Client Queue Storage

The Broker can override the storage type assigned to a document with the storage type
assigned to the client queue. A client queue can have a storage type of volatile or
guaranteed. Volatile client queues can contain volatile documents only. Guaranteed
client queues can contain guaranteed documents and volatile documents.
When the Broker receives a document, it places the document in client queue created for
the subscriber (such as a trigger). If the Broker receives a guaranteed document to which
a volatile client queue subscribes, the Broker changes the storage type of the document
from guaranteed to volatile before placing it in the volatile client queue. The Broker does
not change the storage type of a volatile document before placing it in a guaranteed client
queue.
The following table indicates how the client queue storage type affects the document
storage type.
If document storage type And the client queue storage The Broker saves the document
is... type is... as...
Volatile Volatile Volatile
Guaranteed Volatile
Guaranteed Volatile Volatile
Guaranteed Guaranteed
Note: On the Broker, each client queue belongs to a client group. The client queue
storage type property assigned to the client group determines the storage type for all
of the client queues in the client group. You can set the client queue storage type only
when you create the client group. By default, the Broker assigns a client queue
storage type of guaranteed for the client group created for Integration Servers. For
more information about client groups, see the webMethods Broker Administrator’s
Guide.
Selecting Document Storage Type for a Publishable Document Type

Keep the following points in mind when setting the storage type for a publishable
document type:
 You can only change the document storage type for a publishable document type if
you own the lock on the IS document type (or you have it checked out) and you have
write permission to the IS document type.
 For documents published to the Broker, the storage type assigned to a document can
be overridden by the storage type assigned to the client queue on the Broker.
 Changing a Publication property causes the publishable document type to be out of
sync with the associated Broker document type. For information about synchronizing
document types, see “Synchronizing Publishable Document Types” on page 287.

To assign the storage type for a publishable document type
1 In Package Navigator view of Designer, double‐click the publishable document type
for which you want to set the storage type.
2 In the Properties view, next to the Storage type property, select one of the following:
Select... To...
Guaranteed Specify that instances of this publishable document type should
be stored on disk.
Volatile Specify that instances of this publishable document type should
be stored in memory.
Specifying the Time to Live for a Publishable Document Type

The time‐to‐live value for a publishable document type determines how long instances of
that document type remain on the Broker. The time‐to‐live commences when the Broker
receives a document from a publishing Integration Server. If the time‐to‐live expires
before the Broker delivers the document and receives an acknowledgement of document
receipt, the Broker discards the document. This happens for volatile as well as
guaranteed documents.
For example, suppose that the time‐to‐live for a publishable document type is 10 minutes.
When the Broker receives an instance of that publishable document type, the Broker
starts timing. If 10 minutes elapse and the Broker has not delivered the document or
received an acknowledgement of document receipt, the Broker discards the document.
For a publishable document type, you can set a time‐to‐live value or indicate that the
Broker should never discard instances of the document type.
Related Topics
 “Setting the Time to Live for a Publishable Document Type” on page 282
Setting the Time to Live for a Publishable Document Type

Keep the following points in mind when setting the time‐to‐live for a publishable
document type:
 You can only change the time‐to‐live for an IS document type if you own the lock on
the IS document type (or you have it checked out) and you have write permission to

 Changing a Publication property causes the publishable document type to be out of
sync with the associated Broker document type. For information about synchronizing
document types, see “Synchronizing Publishable Document Types” on page 287.
To set a time-to-live value for a publishable document type
1 In Package Navigator view, double‐click the publishable document type for which
you want to set a time to live.
2 In the Properties view, next to the Discard property, select one of the following:
Select... To...
False Specify that the Broker should never discard instances of this
True Specify that the Broker should discard instances of this
publishable document type after the specified time elapses.
In the Time to live property, specify the time‐to‐live value and
units in which the time should be measured.
Specifying Validation for a Publishable Document Type

In a publish‐and‐subscribe solution, Integration Server validates a published document
against the associated publishable document type. Validation occurs immediately after
the publishing service executes. If Integration Server determines that the published
document is invalid (that is, the published document does not conform to the associated
publishable document type), the publishing service returns a service exception that
indicates the validation error. Integration Server does not publish the document to
webMethods Broker or, in the case of local publishing, to the dispatcher.
While document validation ensures that document subscribers receive valid documents
only, it can be an expensive operation in terms of resources and performance. In some
situations, you might not want to validate the published document. For example, you
might want to disable document validation when publishing documents that were
already validated. Suppose that a back‐end resource, created and validated the document
and then sent it to Integration Server. If Integration Server in turn, publishes the
document to Broker, you might not need to validate the document when publishing it
because it was already validated by the back‐end resource. You might also want to
disable all document validation when publishing native Broker events.

Integration Server provides two settings that you can use to configure validation for
published documents.
 A global setting named watt.server.publish.validateOnIS that indicates whether
Integration Server always performs validation, never performs validation, or
performs validation on a per document type basis. You can set this property using
Integration Server Administrator. For more information about setting this property,
see the webMethods Integration Server Administrator’s Guide.
 A publication property for publishable document types that indicates whether
instances of a publishable document type should be validated. Integration Server
honors the value of this property (named Validate when published) only if the
watt.server.publish.validateOnIS is set to perDoc (the default).
Note: When deciding whether to disable document validation, be sure to weigh the
advantages of a possible increase in performance against the risks of publishing,
routing, and processing invalid documents.
Related Topics
 “Setting Validation for an Individual Publishable Document Type” on page 284
Setting Validation for an Individual Publishable Document Type

You can only change the Validate when published property for an IS document type if you
own the lock on the IS document type (or you have it checked out) and you have write
permission to the IS document type.
To specify validation for instances of a publishable document type
1 In Package Navigator view, double‐click the publishable document type for which
you want to specify validation.
2 In the Properties view, under Publication, set the Validate when published property to one
of the following:
Select... To...
True Perform validation for published instances of this publishable
document type.
This is the default.
False Disable validation for published instances of this publishable
document type.

Editing Document Types

When you make a change to an IS document type, keep the following points 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.) To view a list of
elements that use the IS document type and will be affected by any changes, use the
Find Dependents command on the right‐click menu.
 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.
Related Topics
 “Important Considerations When Modifying Publishable Document Types” on
page 285
Important Considerations When Modifying Publishable Document

Types
 When you modify a publishable document type (for example, delete a field or change
a property), the publishable document type is no longer synchronized with the
corresponding Broker document type. When you save your changes to the
publishable document type, Designer 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.
Designer displays this message only if a Broker is configured for the Integration
Server. After you modify a publishable document type, you need to update the
associated Broker document type with the changes. For information about how to
synchronize document types, see “Synchronizing Publishable Document Types” on
page 287.
 Changes you make to the contents of a publishable document type might require you
to modify the filter for the document type in a trigger condition. For example, if you
add, rename, or move fields you need to update any filter that referred to the
modified fields. You might also need to modify the service specified in the trigger
condition for the Broker/local trigger.

Deleting Publishable Document Types

When you delete a publishable document type, you can do the following:
 Delete the publishable document type on Integration Server and delete the
corresponding document type on the Broker.
 Delete the publishable document type on the Integration Server, but leave the
corresponding document type on the Broker.
Related Topics
 “Deleting a Publishable Document Type” on page 286
Deleting a Publishable Document Type

Before you delete a publishable document type, keep the following in mind:
 You can only delete the associated Broker document type if there are no subscriptions
for it.
 If you intend to delete the associated Broker document type as well, make sure that
the Broker is configured and the Integration Server is connected to it.
 You can only delete a publishable document type if you own the lock (or have the
publishable document type checked out) and have Write permission to it.
 If you delete a Broker document type that is required by another Integration Server,
you can synchronize (push) the document type to the Broker from that Integration
Server. If you delete a Broker document type that is required by a non‐IS Broker
client, you can recover the document from the Broker .adl backup file. See the
webMethods Broker Administrator’s Guide for information about importing .adl files.
To delete a publishable document type
1 In Package Navigator view, select the document type you want to delete.
2 Select Edit > Delete.
If you enabled the deleting safeguards in the Preferences dialog box, and the
publishable document type is used by other elements, Designer displays a dialog box
listing all dependent elements, including triggers and flow services.
For information about enabling safeguards to check for dependents when deleting an
element, see “Configuring Dependency Checking for Elements” on page 38.

Do one of the following:
 If you want to delete the publishable document type on the Integration Server,
but leave the corresponding document type on the Broker, leave the Delete
associated Broker document type on the Broker check box cleared.
 If you want to delete the publishable document type on the Integration Server and
the corresponding document type on the Broker, select the Delete associated Broker
document type on the Broker check box.
Click... To...
Continue Delete the element from the Integration Server. References in
dependent elements remain.
Cancel Cancel the operation and preserve the element in the Integration
Server.
OK Delete the element from Integration Server. (The OK button only
appears if the publishable document type did not have any
dependents.)
Synchronizing Publishable Document Types

When you synchronize document types, you make sure that a publishable document
type matches its associated Broker document type. You will need to synchronize
document types when:
 You make changes to the publishable document type.
 You make changes to the Broker document type. (This is usually the result of a
developer on another Integration Server updating that server’s copy of the
publishable document type and pushing the change to the Broker document type.)
 You make changes to both document types.
 You made a document type publishable when Integration Server was not connected
to the Broker.
 You install packages containing publishable document types on Integration Server.
 You change the client group to which the Integration Server belongs
When you synchronize a publishable document type, you use the synchronization status
to determine which synchronization action to take.
Related Topics
 “Synchronization Status” on page 288
 “Synchronization Actions” on page 289

 “Combining Synchronization Action with Synchronization Status” on page 290
 “Synchronizing a Single Publishable Document Type” on page 292
 “Synchronizing Multiple Document Types Simultaneously” on page 293
 “Synchronizing Document Types in a Cluster” on page 293
 “Synchronizing Document Types Across a Gateway” on page 293
 “Importing and Overwriting References During Synchronization” on page 293
Synchronization Status
Each publishable document type on your Integration Server has a synchronization status
to indicate whether it is in sync with the Broker document type, out of sync with the
Broker document type, or not associated with a Broker document type. The following
table identifies each possible synchronization status for a document type.
Status Description
Updated Locally The publishable document type has been modified on

Integration Server.
Updated on Broker The publishable document type has been modified on the
Broker.
Updated Both Locally The publishable document type and the Broker document type
and on the Broker have both been modified since the last synchronization. You
must decide which definition is the required one and push to or
pull from the Broker accordingly. Information in one or the
other document type is overwritten.
Created Locally The publishable document type was made publishable when
the Broker was not connected or the publishable document type
was loaded on Integration Server via package replication. An
associated Broker document type may or may not exist on the
Broker. If an associated Broker document type exists on the
Broker, synchronize the document types by pulling from the
Broker. If no associated Broker document type exists on the
Broker, create (and synchronize) the document types by
pushing to the Broker.
Removed from Broker The Broker document type associated with the publishable
document type was removed from the Broker. If you want to
recreate the document type on the Broker, push the publishable
document type to the Broker. If you want to delete the
publishable document type on Integration Server, pull from the
Broker.
In Sync with Broker The IS document type and the Broker document type are
already synchronized. No action is required.

Synchronization Actions
When you synchronize document types, you decide for each publishable document type
whether to push or pull the document type to the Broker. When you push the publishable
document type to the Broker, you update the Broker document type with the publishable
document type on your Integration Server. When you pull the document type from the
Broker, you update the publishable document type on your Integration Server with the
Broker document type.
The following table describes the actions you can take when synchronizing a publishable
document type.
Action Description
Push to Broker Update the Broker document type with information from the

Pull from Broker Update the publishable document type with information from the
Broker document type.
Integration Server does not automatically synchronize document types because you
might need to make decisions about which version of the document type is correct. For
example, suppose that Integration Server1 and Integration Server2 contain identical
publishable document types named Customer:getCustomer. These publishable document
types have an associated Broker document type named wm::is::Customer::getCustomer. If a
developer updates Customer:getCustomer on Integration Server2 and pushes the change to
the Broker, the Broker document type wm::is::Customer::getCustomer is updated. However,
the Broker document type is now out of sync with Customer:getCustomer on Integration
Server1. The developer using Integration Server1 might not want the changes made to
the Customer:getCustomer document type by the developer using Integration Server2. The
developer using Integration Server1 can decide whether to update the
Customer:getCustomer document type when synchronizing document types with the Broker.
Note: For a subscribing Integration Server to process an incoming document
successfully, the publishable document type on a subscribing Integration Server
needs to be in sync with the corresponding document types on the publishing
Integration Server and the Broker. If the document types are out of sync, the
subscribing Integration Server may not be able to process the incoming documents. In
this case, the subscribing Integration Server logs an error message stating that the
“Broker Coder cannot decode document; the document does not conform to the
document type, documentTypeName.”

Combining Synchronization Action with Synchronization Status

The effect of a synchronization action on a publishable document type or a Broker
document type depends on the synchronization status of the publishable document type.
The following table describes the result of the push or pull action for each possible
document type status.
Status Action Result
Updated Locally Push to Broker Updates the Broker document type with changes

made to the publishable document type.
Pull from Broker Restores the publishable document type to the
previously synchronized version. Any changes
made to the publishable document type are
overwritten.
Updated on Broker Push to Broker Restores the Broker document type to the
previously synchronized version. Any changes
made to the Broker document type are
overwritten.
Pull from Broker Updates the publishable document type with
changes made to the Broker document type.
Updated Both Push to Broker Updates the Broker document type with changes
Locally and on the made to the publishable document type. Any
Broker changes made to the Broker document type
prior to synchronization are overwritten.
changes made to the Broker document type. Any
changes made to the publishable document type
prior to synchronization are overwritten.
Created Locally Push to Broker If no associated Broker document type exists,
this action creates an associated Broker
document type. If an associated Broker
document type already exists, this action
updates the Broker document type with the
changes in the publishable document type.
Note: If publishable document types for this
Broker document type exist on other Integration
Servers, this action changes the synchronization
status of those publishable document types to
Updated on Broker.

Status Action Result
Pull from Broker If an associated Broker document type exists,

this action establishes the association between
the document types. If changes have been made
to the Broker document type, this action updates
the publishable document type as well.
If an associated Broker document type does not
exist, this action deletes the publishable
document type.
Note: If publishable document types for this
Broker document type exist on other Integration
Servers, this action does not affect the
synchronization status of those publishable
document types.
Removed from Push to Broker Recreates the Broker document type.

Broker
Pull from Broker Deletes the publishable document type.
In Sync with the Push to Broker Pushes the publishable document type to the
Broker Broker. Even though no changes were made to
the Broker document type, if other Integration
Servers contain publishable document types
associated with the Broker document type, the
status of those publishable document types
becomes “Updated on Broker”.
Tip! If a publishable document type is in sync
with the Broker document type, set the action to
Skip.

the Broker document type even though no
changes are made.
Tip! If a publishable document type is in sync
with the Broker document type, set the action to
Skip.
Note: For a publishable document type created for an adapter notification, you can
select Skip or Push to Broker only. A publishable document type for an adapter
notification can only be modified on the Integration Server on which it was created.

Synchronizing a Single Publishable Document Type

You can synchronize a single publishable document type with its corresponding Broker
document type. When you synchronize one publishable document type, keep the
 If you want to Pull from Broker, you need to have write access to the publishable
document type and own the lock on it. For more information about locking elements
and access permissions (ACLs), see “Locking Elements” on page 70 and “Assigning
ACLs” on page 62.
 When you Pull from Broker, Designer gives you the option of overwriting elements
with the same name that already exist on the Integration Server. The Broker
document type might reference elements such as an IS schema or other IS document
types. If the Integration Server you are importing to already contains any elements
with the referenced names, you need to know if there is any difference between the
existing elements and those being imported from the Broker. If there are differences,
you need to understand what they are and how importing them will affect any
integration solution that uses them. For more information about overwriting existing
elements, see “Importing and Overwriting References During Synchronization” on
page 293.
 For a publishable document type created for an adapter notification, you can only
select Push to Broker or Skip.
To synchronize a single publishable document type
1 In Package Navigator view, select the publishable document type that you want to
synchronize.
2 Select File > Sync Document Type. Designer displays the Synchronize dialog box. The
Synchronize dialog box displays the synchronization status of the document type, as
described in “Synchronization Status” on page 288.
3 Under Action, do one of the following:
Select... To...
Push to Broker Update the Broker document type with the publishable

document type.
Pull from Broker Update the publishable document type with the Broker
document type.
Note: The result of a synchronization action depends on the document status. For
more information about how the result of a synchronization status depends on
the synchronization status, see “Combining Synchronization Action with
Synchronization Status” on page 290.

4 If you select Pull from Broker, as the action, Designer enables the Overwrite existing

elements when importing referenced elements check box.
5 If you want to replace existing elements in the Integration Server with identically
named elements referenced by the Broker document type, select the Overwrite existing
elements when importing referenced elements check box. See “Importing and Overwriting
References During Synchronization” on page 293 for more information about this
topic.
6 Click Synchronize to synchronize the two document types
Synchronizing Multiple Document Types Simultaneously

At this time, Designer can synchronize one document at a time only. If you want to
synchronize multiple document types simultaneously, use webMethods Developer.
Synchronizing Document Types in a Cluster

The Broker provides support for a clustered configuration of Integration Servers, that is,
an environment in which multiple Integration Servers are configured to behave as one
Integration Server connected to the Broker. A change in a publishable document type on
one Integration Server does not automatically result in a change to all Integration Servers
in the cluster. You must synchronize each Integration Server with the Broker
individually.
Synchronizing Document Types Across a Gateway

webMethods does not support synchronization of document types across a gateway. (A
gateway connects two Broker territories.) If you set up two or more Broker territories
connected by gateways, the only way to synchronize document types is to replicate
packages between Integration Servers in each territory. For information about replicating
and loading packages from one Integration Server to another see the webMethods
Integration Server Administrator’s Guide.
Importing and Overwriting References During Synchronization

When you create a publishable document type from a Broker document type or
synchronize a publishable document type by pulling a Broker document type from the
Broker, you must decide if you want to overwrite any existing elements associated with
the Broker document type.
For example, suppose that you are creating a publishable document type from a Broker
document type that was created on another Integration Server. The Broker document
type might reference elements such as an IS schema or other IS document types.
However, the Integration Server on which you are creating the publishable document
type might already contain elements with the referenced names. Before you overwrite the
existing elements, you need to know if there are any differences between the existing

elements and those being imported from the Broker. If there are differences, you need to
understand what they are and how importing them will affect any elements that use
them, such as services, IS document types, or triggers.
When you create a new document type from a Broker document type or when you
synchronize document types, you can use the Overwrite existing elements when importing
referenced elements check box to indicate whether existing elements should be overwritten
by imported elements of the same name.
Related Topics
 “What Happens When You Overwrite Elements on the Integration Server?” on
page 294
 “What Happens if You Do Not Overwrite Elements on the Integration Server?” on
page 294
What Happens When You Overwrite Elements on the Integration Server?

If you choose to overwrite existing elements when you are creating a document type or
synchronizing, Integration Server does the following when it encounters existing
elements with the same names as referenced elements:
 If the Write ACL of a referenced element is set to WmPrivate, the Integration Server
skips that element. The Integration Server considers the element to be in sync.
 If the lock can be obtained for all referenced elements and the current user has write
permission for the elements, the Integration Server overwrites the existing elements
and synchronization (or document type creation) succeeds.
During synchronization, if Integration Server cannot overwrite one of the elements
referenced by the Broker document type, the synchronization fails. The Integration
Server does not update any of the referenced elements or the publishable document type.
Similarly, when you create a publishable document type from a Broker document type, if
the Integration Server cannot overwrite one of the elements referenced by the Broker
document type, the Integration Server does not create the publishable document type.
What Happens if You Do Not Overwrite Elements on the Integration Server?

If you choose not to overwrite elements when you create a publishable document type
from a Broker document type, Integration Server will not create the publishable
document type if the Broker document type references elements with the same name as
existing element son the Integration Server.
If you choose not to overwrite elements when you synchronize document types by
pulling from the Broker, Integration Server does not synchronize any document type that
references existing elements on the Integration Server. Integration Server synchronizes
only those document types that do not reference elements.

Testing Publishable Document Types

In order to test a publishable document type in Designer, you must create a launch
configuration for the document type. In the launch configuration, you can specify input
values and publishing method. Designer uses this information to create an instance of the
publishable document type. Integration Server then publishes the document locally or to
the Broker (whichever is specified). Designer displays the results of the publish in the
Publish Results view.
Testing a publishable document type provides a way for you to publish a document
without building a service that does the actual publishing. If you select a publication
action where you wait for a reply document, you can verify whether or not reply
documents are received.
Related Topics
 “Creating a Launch Configuration for a Publishable Document Type” on page 295
 “Testing a Publishable Document Type” on page 297
Creating a Launch Configuration for a Publishable Document Type

Use the following procedure to create are‐usable launch configuration that you can run to
test a publishable document type.
To create a launch configuration for a publishable document type
1 In Package Navigator view, open the publishable document type that you want to
test.
2 Select Run > Run Configurations to open the Run Configurations dialog box.
3 On the Configurations tree, select IS Document (Publishable), and then click .

A new configuration entry appears below IS Document (Publishable) and the launch
configuration options appear on the right‐hand side of the dialog box.
4 In the Name field, enter a new name for your launch configuration. The Publishable
tab displays the name of the Integration Server where the document type resides as
well as the name of the document type.
5 Click the Input tab and specify input values for the publishable document type.
a Enter valid values for the fields defined in the publishable document type or click
Load to retrieve the values from a file. For information about loading input values
from a file, see “Loading Input Values” on page 235.
b Select the Prompt for data at launch check box if you want to view or edit the input
data before the launch configuration runs. This option is selected by default.

c 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 information
about saving input values, see “Saving Input Values” on page 234.
d Click Apply. When you enter values for constrained objects in the Input tab,
Integration Server automatically validates the values. If the value is not of the
type specified by the object constraint, Designer displays a message identifying
the variable and the expected type.
6 Click the Action tab and specify publish settings for the document type.
a Select the type of publishing for the document.
Select... To...
Publish locally to this Integration Publish an instance of the publishable

Server document type to the same Integration Server
to which you are connected.
Publish to the Broker Publish an instance of this publishable
document type to the Broker.
Deliver to a client Deliver an instance of the publishable
document type to a specific client on the
Broker.
Publish locally to this Integration Publish an instance of the publishable
Server and wait for a Reply document type to the same Integration Server
to which you are connected and wait for a
response document.
Publish to the Broker and wait for Publish an instance of this publishable
a Reply document type to the Broker and wait for a
response document.
Deliver to a Client and wait for a Deliver an instance of the publishable
Reply document type to a specific client on the
Broker and wait for a reply document.
b If you selected either Deliver to a client or Deliver to a client and wait for a Reply, specify

the Broker client to which you want to deliver the document. You can enter the
Broker client name or click Browse to select the client. If you click Browse, Designer
displays all the clients connected to your Broker.
Note: Integration Server assigns trigger clients names according to the client prefix
specified on the Settings > Broker screen of the Integration Server Administrator.
c If you selected a publication action in which you wait for a reply, you need to
select the document type that you expect as a reply. You can enter the document
type name or click Browse to select the document type.

If you click Browse, Designer displays all the publishable document types on the
Integration Server to which you are currently connected. In the Elements Name
field, type the fully qualified name of the publishable document type that you
expect as a reply or select it from the Folder list. If the service does not expect a
specific document type as a reply, leave this field blank.
d Under Set how long Designer waits for a Reply, select one of the following:
Select... To...
Wait indefinitely Specify that Designer should wait indefinitely for a reply

document. Designer will wait for the response for the length
of your session on the Integration Server. When you end
your session or close Designer, Designer stops waiting for
the reply.
Wait for Specify the length of time that Designer should wait for the
reply document.
Next to the Wait for option, enter how long you want
Designer to wait for the reply document.
7 Optionally, click the Common tab to define general information about the launch
configuration and to save the launch configuration to a file.
8 Click Apply.
9 Click Run if you want to test the publishable document type now. Otherwise, click
Close.
Testing a Publishable Document Type

Keep the following points in mind when testing a publishable document type:
 If you want to test a join condition in a trigger, you might test each publishable
document type identified in the join condition. If you do this, make sure to use the
same activation number for each publishable document type that you test.
 If your publishable document type 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, you must write a Java
service that generates input values for your service and a flow service that publishes
the document. Then, create a flow service that first invokes the Java service and then
the publishing flow service.
 If you selected a publication action in which you wait for a reply, and Designer
receives a reply document, Designer displays the reply document as the value of the
receiveDocumentTypeName field in the Publish Results view.

 If Designer does not receive the reply document before the time specified next Wait for
elapses, Designer displays an error messages stating that the publish and wait (or
deliver and wait) has timed out. The Publish Results view displays null next to the
receiveDocumentTypeName field to indicate that the Integration Server did not receive a
reply document.
To test a publishable document type
1 In Package Navigator view, select the publishable document type that you want to
test.
2 In Designer
Run > Run As > Publishable Document.
 If a launch configuration exists and Prompt for data at launch is not enabled, the
configuration runs. If Prompt for data at launch is enabled, the Input dialog box
appears. View and edit the input data for the launch configuration, then click Run.
 If more than one launch configuration exists, select the one you want to run from
the Launch Configurations dialog box, and then click Run.
 If a launch configuration does not exist, Designer uses the default launch
configuration. When the Input dialog box appears, enter launch configuration
data for the test in the Input dialog box and then click Run.
Note: The input data is not saved after the default launch configuration runs. If
you want to save the input data in a launch configuration, see “Creating a
Launch Configuration for a Publishable Document Type” on page 295 for
instructions about creating and saving a launch configuration.
Notes:
 Designer displays the instance document and publishing information in the Publish
Results view.
 If you selected a publication action in which you wait for a reply, and Designer
receives a reply document, Designer displays the reply document as the value of the
receiveDocumentTypeName field in the Publish Results view.
 If Designer does not receive the reply document before the time specified next Wait for
elapses, Designer displays an error messages stating that the publish and wait (or
deliver and wait) has timed out. The Publish Results view displays null next to the
receiveDocumentTypeName field to indicate that the Integration Server did not receive a
reply document.

About Universal Names 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 that external protocols (such as SOAP) use to reference a service or document
type on a webMethods Integration Server. For more information about assigning a
universal name to a document type, see “Assigning a Universal Name to a Service or
Related Topics
 “Implicit and Explicit Universal Names” on page 150
 “Deleting an Explicit Universal Name” on page 152
 “The Universal Name Registry” on page 152


12 Working with Variables
A variable can be a String, String list, String table, document, document list, document
reference, document reference list, Object, or Object list. You can use an IS document type
(including a publishable document type) to create a document reference or document
reference list field. You can assign properties and input values for a variable. You can also
apply content constraints and structural constraints to a variable for validation purposes.
Select a variable in the editor to set general properties and constraints for the variable.
Note: Specific properties in the Properties view are enabled or disabled, depending on
the type of variable you have selected.
Related topics
 “Variable Properties” on page 356
 “Creating a Document Reference or a Document Reference List Variable” on page 301
 “Assigning Properties to Variables” on page 302
 “Applying Constraints to Variables” on page 304
Creating a Document Reference or a Document Reference

List Variable
You can use an IS document type (including a publishable 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.
Keep the following points in mind when using IS document types to create document
references or document reference lists.
 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 in the
Input/Output tab. To edit the referenced document or document list, select it in the
Package Navigator, lock it, and then edit its fields in the editor.
 You can also add a document reference by dragging an IS document type from the
Package Navigator to the Document Type editor.

To use a document type to build a document reference or document reference list
1 In Package Navigator view, open the document type that you want to reference.
2 On the editor palette, click and drag one of the following into the editor window:
Click and drag... 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.
3 In the Element Name field, type the fully qualified name of the IS document type or
select it from the list.
4 Click OK.
5 Type the name of the field.
Related topics
 “Applying Constraints to Variables” on page 304
Assigning Properties to Variables

You can specify additional properties for variables. These properties are located in the
Properties view.
On the Properties view, the General category contains the properties of the field and the
Constraints category contains validation constraints for the field.
Related topics
 “Assigning XML Namespaces” on page 302
 “Assigning Display Types to String Variables” on page 304
Assigning XML Namespaces

Although it is not always necessary to do so, you can associate the name of an IS field
(such as an IS document variable) with an XML namespace. When you do so, the local
name is the name of the field and the XML namespace name is the URL that identifies the
namespace. You can also include a prefix as part of the name.

Integration Server automatically assigns an XML namespace to a field (such as an IS
document variable) when it creates a provider Web service descriptor WSDL or a
consumer Web service descriptor from an existing WSDL. Integration Server also
assigns an XML namespace from a schema when it creates a document type from an
existing XML schema.
Related topics
 “Guidelines for Assigning XML Namespaces to Web Service Descriptors” on
page 303
Guidelines for Assigning XML Namespaces to Web Service Descriptors

Use the following guidelines for assigning XML namespaces and prefixes to Web service
descriptors:
 If an IS service signature contains a field name in the format prefix:localName and you
expose that IS service as a Web service operation, then you must associate an XML
namespace property with that field.
 If an IS service is exposed as an RPC‐Literal or RPC‐Encoded Web service operation,
then the top‐level field name in the service signature should not be in the format
prefix:localName and should not be associated with an XML namespace.
 If an IS service is exposed as a Document‐Literal Web service operation, then any field
name in the service signature can be in the format prefix:localName, but it must also be
associated with an XML namespace.
Assigning XML Namespaces and Prefixes to Variables

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, 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.
To assign an XML namespace and prefix to an IS field
1 In the editor, select the field to which you want to assign an XML namespace.
2 In the Properties view, click the XML namespace browse button ( ) and then enter a
value for the XML namespace. To assign a prefix to an IS field, precede the field name
with the prefix followed by a colon (for example, prefix:variableName).
3 Click Okay.

Assigning Display Types to String Variables

Assign a string display type to the string variable to define how you want to input data
for the field.
To assign a string display type to a String variable
1 In the editor, select the String variable to which you want to assign properties.
2 In the Properties view, under General, assign one of the following values to the String
display type field:
Select... If you want the input…
Text Field (default) Entered in a text field

Password Entered as a password, with asterisks reflected instead of
characters
Large Editor Entered in a large text area instead of a text field. This is
useful if you expect a large amount of text as input for the
field, or you need to have TAB or new line characters in the
input
Pick List To be limited to a predefined list of values
Next to Pick list choices, click to define the values that will

appear as choices when Designer prompts for input at run
time.
Note: These options are not available for Objects and Object lists.
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 a Document Type” on page 263.
Related topics
 “Considerations for Object Constraints” on page 305
 “Applying Constraints to a Variable” on page 306
 “Customizing a String Content Type” on page 308
 “Viewing the Constraints Applied to Variables” on page 309
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 386.
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.
 During debugging, 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 in the Pipeline view using
on the toolbar.
Applying Constraints to a Variable
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 Properties view, under Constraints, define the following properties:
Required Specifies whether the selected variable is required to exist at
run time
Select... To...
True Require the selected variable to exist at
run time.
False Make the existence of the variable optional
at run time.
Allow null Specifies whether a variable is allowed to have a null value.
Select... To...
True Allow the variable to have a null value.
False Have the validation engine generate an
error when the variable has a null value.
Allow unspecified If the variable is a document or document list, specifies
fields whether the variable can contain undeclared child variables.
Select... To...
True Allow the variable to contain undeclared
child variables.

False Treat any child variables that exist in the
pipeline but do not appear in the declared
document field 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. 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.
3 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 webMethods Developer User’s Guide.)
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 308.
 If you want to use a simple type from an IS schema as the content constraint, click
Browse. 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.
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.
Note: In webMethods Developer, you can customize the content type by
changing the constraining facets applied to the type. This functionality is not
available in Designer. For more information, see webMethods Developer User’s
Guide.
4 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 386.
5 Repeat this procedure for each variable to which you want to apply constraints in the
IS document type, specification, service input, or service output.

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. Designer saves the
changes as a new content type named contentType_customized. For example, if you
customize the string content type, Designer saves the new content type as
string_customized.
Note: In webMethods Developer, you can edit a simple type definition in an IS
schema. This functionality is not available in Designer. For more information about
editing simple type definitions, see webMethods Developer User’s Guide.
When customizing a content type, keep the following points in mind:
 When you edit the constraining facets, you can only make the constraining facet
values more restrictive. The constraining facets cannot become less restrictive.
Note: Use webMethods Developer to edit the constraining facets applied to a
content type. This functionality is not available in Designer. For more information
about setting values for constraining facets, see webMethods Developer User’s Guide.
 The constraining facets you can specify depend on the content type. For more
information the constraining facets for each content type, see webMethods Developer
User’s Guide.
 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.)
Note: Use webMethods Developer to edit simple type definitions. This
functionality is not available in Designer. For more information about editing
simple type definitions, see webMethods Developer User’s Guide.
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 view, 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 Browse. 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 Customize. Designer 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). Designer 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 constraining facets, see webMethods
Developer User’s Guide.
5 Click OK. Designer 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, Designer 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! Integration Server throws exceptions at design time if the constraining facet
values for a content type are not valid. For more information about these exceptions,
Viewing the Constraints Applied to Variables

Designer displays small symbols next to a variable icon to indicate the constraints
applied to the variable. Designer displays variables in the following ways:
Variable Constraint status Variable Properties

Required field. The Required property is set to True.
Optional field. The Required property is set to False.
Required field with The Content type property specifies an

content type constraint IS schema or XML schema.
Optional field with content The Required property is set to False
type constraint and the Content type property specifies
an IS schema or XML schema.

Note: Designer displays the ‡ symbol next to String, String List, and String table
variables with a content type constraint only. Designer 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 386.

II Reference
 “Properties” on page 321
 “Icons” on page 389
 “Toolbars” on page 395
 “Supported and Unsupported Elements in webMethods Designer” on page 405

II Reference

13 Integration Server Preferences
Field Description
Name Name to use for this Integration Server.
Host Name or Host name or IP address of the Integration Server to which Designer
IP Address is to connect.
Port Port number on which Integration Server listens for requests.
Default By default, a new Designer installation includes a server definition
named Default. This server is marked as the default server and is
configured to use localhost:5555. If a user creates or edits a process
and no server definitions are connected, Designer automatically
connects to the default server definition.
Status Indicates whether or not Designer is connected to the Integration
Server specified in this definition.
Possible statuses are Connected, Not connected, No userid and password.
To connect to an Integration Server that has the No userid or password
status, click select the associated definition, click Edit, and enter the
userid and password information.
Offline Specifies whether Designer is to attempt to connect to this
Integration Server.
By default, if a Process Development user creates or edits a process
when no server definitions are connected, Designer will
automatically try to connect to a server. Often, when connecting to a
server, Designer will prompt the user to enter credentials. To
prevent Designer from repeatedly prompting for credentials, you
can place the server definition offline.

13 Integration Server Preferences

14 Service Development Preferences
 “Adapter Service/Notification Error Preferences” on page 315
 “Flow Service Editor Preferences” on page 316
 “Package Navigator Preferences” on page 317
 “Publishable Document Type Preferences” on page 319
Adapter Service/Notification Error Preferences

On the Adapter Service/Notification Error preferences page, you can specify whether
data is automatically validated upon entry and whether metadata is automatically
reloaded.
Preference Description
Automatic data validation When selected, value checking is performed on all
user input. This safeguard makes sure that all user
data are valid against current resource data.
Automatic polling of adapter When selected, Designer will reload metadata from
metadata the adapter every time it creates a new adapter
service/notification. This option can be useful for
adapter developers that are working on designing the
metadata.
Related Topics

Flow Service Editor Preferences

Use thee Flow Service Editor preferences page to customize settings for working in the
Flow service editor.
Services List Use this list to specify the list of services that appear
under Insert on the flow service editor Palette view.
Each row in the list represents a single command on
the menu. Commands will appear on the menu in
the order you specify them. You may add as many
services as you need.
The Name column specifies a label for the service.
The Service column specifies the services associated
with the labels on the menu.
Grid Properties When Enable Grid is selected, Designer displays a grid
on the Layout tab of the flow service editor. Use Grid
Width and Grid Height to specify the size of the grid.
Label Properties In the Layout tab, specifies the height and width
used for displaying the name of the service for an
INVOKE step.
Related Topics

Package Navigator Preferences

Use the Package Navigator preferences page to specify safeguards when moving,
renaming, and deleting elements in the Package Navigator view and to indicate the
number of elements Designer caches for each session.
Confirm before deleting When selected, instructs Designer to notify you
before deleting an element used by other elements,
such as flow services, IS document types,
specifications, or triggers. If Designer finds
elements that depend on the element being deleted,
Designer lists those dependents and prompts you
to delete the element anyway or cancel the action. If
you clear this check box, Designer deletes the
element without prompting you.
Prompt before updating dependents When selected, instructs Designer to alert you
when renaming/moving when dependents exist. Dependents are elements
that use the selected element, such as flow services,
IS document types, specifications, or triggers.
 If dependents exist, Designer lists those
dependents before renaming or moving the
selected element and prompts you to:
 Rename/move the selected element and update
dependent elements with the new name and
location.
 Rename/move the selected element only.
 Cancel the action.
If you clear this check box, Designer automatically
updates dependents without prompting you.
Update local references when When selected, Designer updates local references
pasting multiple elements when copying and pasting a group of elements.
When two elements within a group refer to each
other, it is called a local reference. If you clear this
check box, Designer retains the original references
in the copied elements.

Automatically unlock upon save When selected, Designer automatically unlocks
(non-VCS servers only) elements after you save changes to them. This
prevents you from forgetting to unlock elements;
however, it may not be the best option if you save
periodically while editing an element. (Not
applicable for Java/C services.)
Important! Do not select this option if the VCS
Integration feature is enabled; it will cause
synchronization problems with the VCS repository.
Hide generated flow services When selected, Designer does not display flow

services automatically generated by a process in the
Number of elements to cache Specifies the number of elements that you want to
cache per Designer session. The higher the number
of elements, the more likely an element will be in
the cache, which reduces network traffic and
speeds up Designer by caching elements that are
frequently used. The total number of cached
elements includes elements on all the servers to
which you are connected.
Click Clear Cache to remove all cached elements
from memory. Clearing the cache does not remove
flow services with breakpoints, flow services that
are currently being debugged, and unsaved
elements. Keep in mind that the cache is
automatically cleared when you close Designer or
when you refresh the session.
Reset Tip Dialogs Re‐enables message boxes and reminders that have
been disabled with the Don't Show This Again check
box.
Related Topics

Publishable Document Type Preferences
Display timeout message When selected, Designer displays a message if the
timeout limit for deliver and wait or publish and
wait request elapses before Designer receives a
response.
Related Topics
 “Adapter Service/Notification Error Preferences” on page 315
 “Testing Publishable Document Types” on page 295


15 Properties
Integration Server property information is available from the Service Development >
Package Navigator view of Designer.
Use the Properties dialog box to view and edit properties for Integration Servers and
packages. You can also use the Properties dialog box to view general information and
permissions for Integration Server elements such as document types, services, flow steps,
JMS triggers, Web service connectors, and Web service descriptors.
You can open the Properties dialog box by selecting the server, package, or element in
Package Navigator view and selecting File > Properties. You can also open the Properties
dialog box by right‐clicking the server, package, or element and selecting Properties.
You can view and configure property information for the following Integration Server
components:
 “Integration Server Properties” on page 321
 “Element Properties” on page 330
 “Document Type Properties” on page 332
 “JMS Trigger Properties” on page 336
 “Link Properties” on page 345
 “Service Properties” on page 347
 “Variable Properties” on page 356
 “Web Service Connector Properties” on page 360
 “Web Service Descriptor Properties” on page 365
Integration Server Properties

You can view information about an Integration Server and assign event subscribers,
permissions, and unlock elements on the server in the Properties dialog box.
To open the Properties dialog box, click the Integration Server in the Package Navigator
of Designer and select File > Properties.

15 Properties
Related Topics
 “Event Manager Properties” on page 322
 “Server ACL Information” on page 323
 “Server Information” on page 324
 “Server Locked Elements” on page 325
Event Manager Properties

Use the Event Manager page to subscribe to an event and to view, edit, suspend and/or
delete an existing event subscription on the current server.
To open this page, select File > Properties > Event Manager.
View event subscribers Specifies the type of event whose subscriptions are displayed

for in this page. Select the event type for which you want to add,
edit, or delete a subscription.
The table in this page displays subscribers to the selected
event type as follows:
Service The fully qualified name of the
subscriber (the event handler that
executes when the event occurs).
When you add a subscription, you can
use the browse button to select the
service.
Filter A pattern string to further specify the
events this event handler subscribes to.
The information for which you create a
filter depends on the event type you are
subscribing to.
The asterisk (*) character represents any
string of characters and is the only wild‐
card character allowed in the pattern
string. All other characters are treated
literally. Pattern strings are case
sensitive.

15 Properties
Comment An optional comment describing this
subscription.
Enabled Whether this subscription is currently
active or inactive. Set this parameter to
true to activate the subscription. Set this
parameter to false to deactivate a
subscription.
You use the buttons in this page to add, edit, and delete a subscription.
Use this button... To...
Add a subscription.
Insert a blank row for a subscription.
Delete the selected subscription.
Edit the selected subscription.
Server ACL Information

Use the ACL Information page to list the Access Control Lists (ACLs) contained on the
Integration Server to which you are connected.
To open this page, select File > Properties > Permissions. This information is read only; to
edit ACLs, users, and groups, use the Integration Server Administrator.
ACLs The ACLs defined on the Integration Server to which you are
connected. These include the default ACLs that were
installed with the server. To edit an ACL, use the Integration
Server Administrator.

15 Properties
User Group Association  Allowed. The user group(s) that have been explicitly

for '[ACL name]' allowed to access the packages, folders, services, or other
elements associated with this ACL. To edit a user group,
use the Integration Server Administrator.
 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 for Displays the names of users that the ACL authorizes, given
'[ACL name]' the current settings in the Allowed and Denied lists. The
server builds this list by looking at the groups to which each
user belongs and comparing that to the groups to which the
ACL allows or denies access. For details on how the server
determines access, see the webMethods Integration Server
Server Information
View general information about a server from the Server Information page. To open this
page, select File > Properties > Server Information.
Type Type of server. This will be Integration Server.
Name Name assigned to the Integration Server.
Location Host name and port address of the Integration Server.
User Name The user name you use to connect to this Integration Server.
Connected Indicates whether or not you are currently connected to this
Integration Server.
VCS Enabled Indicates whether this Integration Server is configured to use
a version control system (VCS)
Proxy Specifies the proxy server as set on Window > Preferences >
General > Network Connections.

15 Properties
Server Locked Elements

Use the Server Locked Elements page to unlock elements for the selected server.
To open this page, in Designer select File > Properties > Server Locked Elements.
Select the Elements to Select the elements that you want to unlock. CTRL+click to

Unlock select more than one or click Unlock All to unlock all of the
elements in the list.
Package Properties
Use the Properties dialog box to view information about packages on the Integration
Server and to assign package dependencies, permissions, replication services, startup
and shutdown services.
To open the Properties dialog box, click the package in the Package Navigator of Designer
and select File > Properties.
Related Topics
 “Package Information” on page 325
 “Package Dependencies” on page 325
 “Package Settings” on page 327
 “Package Permissions” on page 328
 “Package Replication Services” on page 328
 “Package Startup/Shutdown Services” on page 329
Package Information
The Element Information page displays the type and name of the Integration Server
package.
To open this page, click the package in the Package Navigator of Designer and select File >
Properties > Element.
Package Dependencies
The Package Dependencies page displays the packages on which this package is
dependent. For example, if a package needs the services in another package to load
before it can load, you need to set up package dependencies. You might also want to

15 Properties
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.
Properties > Package Dependencies.
Package The name of the package you want webMethods Integration Server to
load before the package selected in Package Navigator.
Version The version number of the package you want loaded.
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 (*) 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.*. To specify versions 3.1 or later, type
3.1.*.
You use the buttons in this page to add, edit, and delete a package dependency.
Add a package dependency.
Insert a blank row for a package dependency.
Delete the selected package dependency.
Edit the selected package dependency.

15 Properties
Package Settings
The Package Settings page displays general information about a package including
package and JVM versions, build and patch numbers, publishers, and patch history.
Properties > Package Settings.
Package version Specifies the version number for the package. Version numbers

need to be in one of the following formats: X.x or X.x.x (for example,
1.0, 2.1, 2.1.3, or 3.1.2). By default, Designer assigns the version
number 1.0 to a new package.
Build Displays 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 regenerated. For example, a user might generate version
1.0 of the “Finance” package ten times and assign build numbers
1,2,3…10 to the different generations or builds of the package.
The build number is not the same as the package version number.
One version of a package might have multiple builds.
Description Displays a brief description of the package written by the user who
created the package release.
JVM version Displays the version of the JVM (Java virtual machine) required to
run the package.
Publisher Displays the name of the publishing server that created the package
release.
Patch number Displays the patch numbers included in this release of the package.
Patch history Displays a list of all the patches installed for this package release.
When the server administrator installs a full release of the 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.
Name The name of the package.
Version The version number assigned to the 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 (either full
release or a patch) is regenerated.

15 Properties
Description A brief description of the package or patch written
by the user who created the package release.
Time The time at which the package release (patch) was
created.
JVM Version The version of the JVM (Java virtual machine)
required to run the package.
Publisher The name of the publishing server that created the
package release.
Patch Number The patch numbers included in this release of the
package.
Package Permissions
You assign an ACL to an element in the Permissions page of the Properties dialog box.
Depending on the element you select, certain access levels are displayed. For example,
for a package, you can only set List access. For details about the different levels of access
available for elements, see the webMethods Integration Server Administrator’s Guide.
Properties > Permissions.
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.).
Package Replication Services

The Replication Services page of the Properties dialog box specifies the services assigned
as replication services for the package. A replication service is one that the webMethods
Integration Server automatically executes when you create a release of a package (full or
partial) or when you create an archive for a package. 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.
Properties > Replication Services.
You use the following buttons on the Replication Services page to add, edit, and remove

15 Properties
Add a replication service.
Insert a blank row for a replication service.
Delete the selected replication service
Edit the selected replication service.
Package Startup/Shutdown Services

You use the Startup/Shutdown Services page of the Properties dialog box to add or
remove the services that you want webMethods Integration Server to automatically
execute when it loads or unloads a package into or from memory.
Properties > Startup/Shutdown Services.
Startup services Displays the list of services that can be used as startup services and

the list of assigned startup services in the package. A startup service
is one that the webMethods Integration Server automatically
executes when it loads a package into memory. Startup services are
useful for generating initialization files or assessing and preparing
(e.g., setting up or cleaning up) the environment before the server
loads a package. However, you can use a startup service for any
purpose. For example, you might want to execute a time‐consuming
service at startup so that its cached result is immediately available to
client applications.
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.
Available services Displays a list of the services that can be used as startup services for

the package. Any service in the package can be a startup service.
After you select a service as a startup service, the service does not
appear in the Available services list.
Selected services Displays the startup services for the package.
You use the following buttons under Startup services to add and
remove startup services.

15 Properties
Add the service selected in Available services as a
startup service for the package.
Remove the service selected in Selected services as
a start up service for the package.
Shutdown Displays the list of services that can be used as shutdown services
services and the list of assigned shutdown services in the package. A
shutdown service is one that the webMethods Integration Server
automatically executes when it unloads a package 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.
Available services Displays a list of the services that can be used as shutdown services
for the package. Any service in the package can be a shutdown
service. After you designate a service as a shutdown service, the
service does not appear in the Available services list.
Selected services Displays the shutdown services for the package.
You use the following buttons under Shutdown services to add and
remove startup services.
Add the service selected in Available services as a
shutdown service for the package.
Remove the service selected in Selected services as
a shutdown service for the package.
Element Properties
Use the Properties dialog box to view information about any Integration Server element
listed in the Package Navigator. Integration Server elements include folders, subfolders,
document types and services.
To open the Properties dialog box, click any Integration Server element in the Package
Navigator of Designer and select File > Properties.
Related Topics
 “Element Information” on page 331
 “Element Permissions” on page 331

15 Properties
Element Information
The Element Information page displays the type and name of the Integration Server
element.
To open this page, click the element in the Package Navigator of Designer and select File >
Properties > Element Information.
Element Permissions
You assign an ACL to an element in the Permissions page of the Properties dialog box.
Depending on the element you select, certain access levels are displayed. For example,
for a package, you can only set List access. For details about the different levels of access
available for elements, see the webMethods Integration Server Administrator’s Guide.
The ACLs assigned to an element are mutually exclusive; that is, an element can have
different ACLs assigned for each level of access. For example, the following element has
the Developers ACL assigned for Read access and the Administrators ACL assigned for
Write access.
To open this page, click the element in the Package Navigator of Designer and select File >
Properties > Permissions.
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.

15 Properties
Enforce execute ACL  When top-level service only. The Integration Server performs

ACL checking against the service when it is directly
invoked from a client or DSP. For example, suppose a
client invokes the OrderParts service on server A. After
checking port access, server A checks the Execute ACL
assigned to OrderParts to make sure the requesting user is
allowed to run the service. It does not check the Execute
ACL when other services invoke OrderParts.
 Always. The Integration Server performs ACL checking
against the service when it is directly invoked from a
client as well as when it is invoked from other services.
For example, suppose the OrderParts service is invoked
from a browser, as well as by the ProcessOrder and
AddToDatabase services. If Always is set on OrderParts, the
server performs ACL checking on OrderParts three times
(once when it is invoked from the browser and twice
when it is invoked by ProcessOrder and AddToDatabase).
Element General Properties

General properties for the element you select in the Package Navigator appear in the
Properties view. From the Properties view you can also view and set permissions for the
element.
Name Local name of the element.
Server Server definition name for the Integration Server on which
the element resides.
URL URL to the Integration Server on which the element resides.
Full name Fully qualified name of the element.
Package Package in which the element is located.
Document Type Properties

Use the Properties view to view information about document types on the Integration
Server and to assign permissions, publication properties, and universal names.
To view properties for a document type, double‐click the document type in the Package
Navigator of Designer.
Related Topics

15 Properties
 “General Properties” on page 333
 “Publication Properties” on page 333
General Properties
In the Properties view, under General, you can assign an ACL to a document type. You
can also add a comment to the document type.
Permissions Click to assign or view ACL permissions to a document type.

Comments Comments about the document type.
Publication Properties
In the Properties view, under Publication, you specify whether a document type can be
published and subscribed to and specify the properties of published instances of a
document type.
Publishable Specifies whether the document type can be published and
subscribed to. For details, see the Publish‐Subscribe Developer’s
Guide.
Broker doc type Displays the name of the corresponding document type on the
Broker. This property displays Not Publishable if the document
type cannot be published. This property displays Publishable
Locally Only if instances of the document type can be published
and subscribed to within this Integration Server only.
Discard Indicates whether the Broker discards instances of this
publishable document type after the time specified in the Time
to live property elapses.
Select... To...
False Instructs the Broker to never discard
instances of this publishable document type.
True Instructs the Broker to discard the document
after the period specified in Time to live
elapses.

15 Properties
Time to live Specifies how long the Broker keeps instances of this

publishable document type. If the time to live elapses before a
subscriber retrieves the document and sends an
acknowledgement, the Broker discards the document.
Storage type Specifies whether instances of this document type are stored in
memory or on disk.
Select... To...
Volatile Volatile documents are stored in memory and
provide at most once processing. Volatile
documents are never acknowledged and will
be lost if the resource on which they reside
shuts down.
Guaranteed Guaranteed documents are saved to disk and
provide at least once processing or exactly‐
once processing. Guaranteed documents will
be recovered upon restart if the resource on
which they reside shuts down. Resources
return acknowledgements for guaranteed
documents after successfully storing or
processing the document. The
acknowledgment allows the sending resource
to remove its copy of the document from disk
storage.
Validate when Specifies whether Integration Server validates published
published instances of this document type.
Select... To...
True Perform validation for published instances of
this document type.
False Disable validation for published instances of
this document type.
Note: Integration Server ignores the value of the Validate when

published property if the watt.server.publish.validateOnIS
property is set to always or never.

15 Properties
Universal Name Properties

You can specify a unique public identifier that external protocols (such as SOAP) use to
reference a document type on an Integration Server. Every document type on an
Integration Server has an explicit universal name in addition to its regular implicit
webMethods name. If you omit or delete a document typeʹs explicit universal name, it
still retains its implicit universal name.
In the Properties view, under Universal Name, you assign a universal name to a document
type.
A universal name has two parts: a namespace name and a local name.
Namespace The URI that will be used to qualify the name of this document type.
name You must specify a valid absolute URI.
Local name A name that uniquely identifies the 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.
Related Topics
Flow Step Properties

Use the following links to view properties for webMethods flow steps:
 “SEQUENCE Properties” on page 382

15 Properties
JMS Trigger Properties

Use the following categories of the Properties view to determine the run‐time behavior of
a JMS trigger.
To view properties for a JMS trigger, double‐click the trigger in the Package Navigator of
Designer.
Related Topics
 “General Properties for a Non Transactional JMS Trigger” on page 336
 “General Properties for a Transactional JMS Trigger” on page 338
 “Message Processing” on page 339
 “Fatal Error Handling” on page 340
 “Transient Error Handling with a Non Transactional JMS Trigger” on page 340
 “Transient Error Handling with a Transactional JMS Trigger” on page 342
 “Exactly Once Processing” on page 343
General Properties for a Non Transactional JMS Trigger

In the Properties view, under General, you specify whether a JMS trigger is enabled, set
the transaction type, specify the acknowledgement mode, expiration, and execution user
credentials.
Name Name of the JMS trigger.
Enabled Specifies whether the JMS trigger is enabled or disabled.
Select... To...
True Enable the JMS trigger
False Disable the JMS trigger.
Transaction type Indicates whether or not the JMS trigger receives and
processes messages as part of a transaction.
Value Description
NO TRANSACTION The JMS trigger does not receive and
process message as part of a transaction.
XA TRANSACTION The JMS trigger receives and processes
messages as part of an XA transaction
LOCAL The JMS trigger receives and processes
TRANSACTION messages as part of a local transaction.

15 Properties
Note: Designer sets the transaction type value based on the
transaction type specified for the JMS connection alias
associated with the JMS trigger.
Acknowledgement mode Indicates how the JMS trigger acknowledges messages it

receives to the JMS provider.
Select... To...
AUTO_ACKNOWLE Automatically acknowledge the
DGE message when it is received by the JMS
trigger. The Integration Server will
acknowledge the message before the
trigger completes processing. The JMS
provider cannot redeliver the message if
Integration Server becomes unavailable
before message processing completes.
CLIENT_ACKNOWL Acknowledge or recover the message
EDGE only after the JMS trigger processes the
message completely.
DUPS_OK_ACKNO Lazily acknowledge the delivery of
WLEDGE messages. This may result in the
delivery of duplicate messages.
Note: Designer displays the Acknowledgement mode property

only the value of the Transaction type property is NO
TRANSACTION.
Join expires Indicates whether the join expires after the time period

specified in Expire after.
Select... To...
True Indicates that Integration Server stops
waiting for messages from the
remaining destination in a join after the
time specified in Expire after elapses.
False Indicates that the join does not expire.
That is, Integration Server waits
indefinitely for messages from the
remaining destinations in the join.

15 Properties
Expire after Specifies how long Integration Server waits for the remaining

documents in the join. The default join time‐out is 1 day.
Execution user Specifies the name of the user account whose credentials
Integration Server uses to execute a service associated with
the JMS trigger. You can specify a locally defined user
account or a user account defined in a central or external
directory.
General Properties for a Transactional JMS Trigger

In the Properties view, under General, you specify whether a JMS trigger is enabled, set
credentials.
Name Name of the JMS trigger.
Enabled Specifies whether the JMS trigger is enabled or disabled.
Select... To...
True Enable the JMS trigger
False Disable the JMS trigger.
Transaction type Indicates whether or not the JMS trigger receives and
processes messages as part of a transaction.
Value Description
NO The JMS trigger does not receive and
TRANSACTION process message as part of a transaction.
XA TRANSACTION The JMS trigger receives and processes
messages as part of an XA transaction
LOCAL The JMS trigger receives and processes
TRANSACTION messages as part of a local transaction.

15 Properties
Note: Designer sets the transaction type value based on the
transaction type specified for the JMS connection alias
associated with the JMS trigger.
Execution User Specifies the name of the user account whose credentials

Integration Server uses to execute a service associated with
the JMS trigger. You can specify a locally defined user
account or a user account defined in a central or external
directory.
Message Processing
In the Properties view, under Message processing, you enable or disable a JMS trigger, set
credentials.
Processing mode Specifies how Integration Server processes messages

received by the JMS trigger. You can specify serial or
concurrent message processing.
Select... To...
Serial Specify that Integration Server should
process messages received by the trigger
one after the other.
Concurrent Specify that Integration Server should
process multiple messages for this trigger
at one time.
Max execution threads Specify the maximum number of messages that Integration
Server can process concurrently. Integration Server uses one
thread to process each message. The default is 1 server
thread.
Max batch messages Specify the maximum number of messages that the trigger
service can receive at one time. If you do not want the trigger
to perform batch processing, leave this property set to 1. The
default is 1.
Note: For a transacted JMS trigger, the Max batch messages

property must be set to 1.

15 Properties
Fatal Error Handling

In the Properties view, under Fatal error handling, you specify wether the Integration
Server should suspend the JMS trigger when an exception occurs during trigger service.
Suspend on Error Specifies that the Integration Server suspends the JMS trigger

when an exception occurs during trigger service execution.
This property is available for serial triggers only.
Select... To...
True Instruct Integration Server to suspend the
trigger when a trigger service ends with a
fatal error.
False Indicate that Integration Server should not
suspend the JMS trigger when a trigger
service ends with a fatal error
Transient Error Handling with a Non Transactional JMS Trigger

When building a trigger, you can specify what action Integration Server takes when the
trigger service fails because of a transient error caused by a run‐time exception. That is,
you can specify whether or not Integration Server should retry the trigger.
In the Properties view, under Transient error handling, you specify whether or not
Integration Server should retry the trigger.
Max retry attempts Specifies the maximum number of times Integration Server

should re‐execute the trigger service when the trigger service
ends because of a transient error that causes an
ISRuntimeException. The default is 0 attempts (indicating the
trigger service does not retry).
Retry interval Specifies the length of time Integration Server waits between
retry attempts. The default is 10 seconds.
On retry failure Indicates how Integration Server handles a retry failure for a
JMS trigger. A retry failure occurs when Integration Server
reaches the maximum number of retry attempts and the trigger
service still fails because of an ISRuntimeException.

15 Properties
Select... To...
Throw exception Indicate that Integration Server throws a

service exception when the last allowed retry
attempt ends because of an
ISRuntimeException.
Suspend and Indicate that Integration Server suspends the
retry later trigger when the last allowed retry attempt
ends because of an ISRuntimeException.
Integration Server retries the trigger service at
a later time when the resources needed by the
trigger service become available.
On transaction Indicates how Integration Server handles a transient error that
rollback occurs during service execution, resulting in the entire
transaction being rolled back.
Select... To...
Recover only Indicate Integration Server recovers the

message back to the JMS provider. Integration
Server receives the message again almost
immediately.
Suspend and Indicate that Integration Server suspends the
recover JMS trigger and then recovers the message
back to the JMS provider. Integration Server
executes the trigger service at a later time
when the resources needed by the trigger
service become available.

15 Properties
Resource monitoring Specifies the service that Integration Server executes to

service determine whether the resources needed by the JMS trigger are
available and if the trigger can be resumed. Integration Server
schedules a system task to execute the resource monitoring
service when one of the following occurs:
 The trigger service ends because of a retry failure and the On
retry failure property is set to Suspend and retry later.
 The trigger service is part of a transacted JMS trigger and the
On transaction rollback property is set to Suspend and recover.
 The document resolver service used for exactly‐once
processing ends because of a run‐time exception and the
watt.server.trigger.preprocess.suspendAndRetryOnError is
set to true.
Note: A resource monitoring service must use the
pub.trigger:resourceMonitoringSpec as the service signature.
Transient Error Handling with a Transactional JMS Trigger

When building a trigger, you can specify what action Integration Server takes when the
trigger service fails because of a transient error caused by a run‐time exception. That is,
you can specify whether or not Integration Server should retry the trigger.
Integration Server should retry the trigger.
On transaction rollback Indicates how Integration Server handles a transient error

that occurs during service execution, resulting in the entire
transaction being rolled back.
Select... To...
Recover only Indicate Integration Server recovers the

message back to the JMS provider.
Integration Server receives the message
again almost immediately.

15 Properties
Suspend and Indicate that Integration Server suspends

recover the JMS trigger and then recovers the
message back to the JMS provider.
Integration Server executes the trigger
service at a later time when the resources
needed by the trigger service become
available.
Resource monitoring Specifies the service that Integration Server executes to
service determine whether the resources needed by the JMS trigger
are available and if the trigger can be resumed. Integration
Server schedules a system task to execute the resource
monitoring service when one of the following occurs:
 The trigger service ends because of a retry failure and the
On retry failure property is set to Suspend and retry later.
 The trigger service is part of a transacted JMS trigger and
the On transaction rollback property is set to Suspend and
recover.
 The document resolver service used for exactly‐once
processing ends because of a run‐time exception and the
watt.server.trigger.preprocess.suspendAndRetryOnError
is set to true.
Note: A resource monitoring service must use the
pub.trigger:resourceMonitoringSpec as the service signature.
Exactly Once Processing

You can configure exactly‐once processing for a JMS trigger. Exactly‐once processing
ensures that a trigger processes a persistent message once and only once. Integration
Server provides exactly‐once processing by determining whether a message is a copy of
one previously processed by the trigger. Designer provides three duplicate detection
methods: redelivery count, document history, and a document resolver service.
In the Properties view, under Exactly once, you configure exactly‐once processing for a
JMS trigger.

15 Properties
Detect duplicates Enables exactly‐once processing for the JMS trigger and

instructs the server to check a message’s redelivery count to
determine whether the trigger has received the message
before.
Select... To...
True Specifies that exactly‐once processing is
provided for documents received by this
trigger and instructs the server to check a
document’s redelivery count to determine
whether the trigger received the document
previously. The redelivery count indicates the
number of times the routing resource has
redelivered a document to the trigger.
False Specifies that exactly‐once processing is not
provided for documents received by this
trigger.
Note: The Integration Server provides exactly‐once
processing for guaranteed documents only.
Use history Indicates whether a document history database will be

maintained and used to determine whether a message is a
duplicate.
Select... To...
True Indicates that Integration Server maintains a
history of messages processed by the trigger.
When the trigger receives a message, the
Integration Server compares the message’s
universally unique identifier (UUID) to the
UUIDs of messages processed by the trigger.
If there is a match, the Integration Server
either determines the second message is a
duplicate and discards it or, if the first
message has not finished processing, marks
the second message’s status as In Doubt.
False Indicates Integration Server does not
maintain a document history database. The
Integration Server will not use document
history to determine whether a message is a
duplicate of one already processed by the
trigger.

15 Properties
Note: To perform duplicate detection using a document
history database, the audit subsystem must be stored in a
relational database and the Integration Server Administrator
must define a JDBC connection pool for the Integration
Server to use to connect to the document history database.
History time to live Specifies the length of time the document history database

maintains an entry for a message processed by the JMS
trigger. During this time period, the Integration Server
discards any messages with the same universally unique
identifier (UUID) as an existing document history entry for
the trigger. When a document history entry expires, the
Integration Server removes it from the document history
database. If the trigger subsequently receives a message with
same UUID as the expired and removed entry, the server
considers the copy to be new because the entry for the
previous message has been removed from the database.
Document resolver Specifies the service that you created to determine whether
service message’s status is New, Duplicate, or In Doubt. Click to
select a service from a list.
The document resolver service must use the
pub.publish:documentResolverSpec to define the service signature.
Link Properties
Use the Properties view to apply conditions to the link you have drawn between two
variables or specify which element of an array you want to link to or from.
To view properties for a link, double‐click the link in the Pipeline editor.
Related Topics
 “General Link Properties” on page 346

15 Properties
General Link Properties
Evaluate copy condition Specifies whether Integration Server evaluates a condition

applied to a link before executing the link.
Select... To...
True Instruct Integration Server to execute the link
only if the condition specified in Copy
Condition evaluates to true.
False Instruct Integration Server to execute the link
without evaluating it against a copy
condition.
Copy condition Specifies the expression that must evaluate to true before the
Integration Server will execute the link between fields. The
server evaluates the condition at run time only if the Evaluate
copy condition property is set to True. Click to specify a
condition. Use the syntax provided by webMethods to write
the condition. For details on the syntax, see the webMethods
Developer User’s Guide.
Indices To specify which element in an array variable you want to
link to or from, click . Select one of the following from the
Link Indices page:
Select... To...
Source Display the variables for which you need to
specify an array index. You only need to
specify indexes for Source variables if the
source variable (the variable you are linking
from) is an array or is a child of an array.
Index
Specifies the array index for the element
whose value you want to link to the target
variable.

15 Properties
Destination Displays the variables for which you need to
specify an array index. You only need to
specify indexes for Destination variables if
the target variable is an array or is the child of
an array.
Index
Specifies the array index for the element to
which you want to link the source variable.
Service Properties
To view properties for a service, double‐click the service in the Package Navigator of
Designer. In the Properties view, under Service Properties, you can configure the Runtime,
Retry on ISRuntimeException, Universal Name, Audit, and Output Template properties for the
service.
Note: A Web service connector element also uses the Runtime, Universal Name, Audit, and

Output Template categories of the Properties view, but does not use the Retry on
ISRuntimeException properties.
To edit the properties for a service, you must have Write access to it and own the lock.
Related Topics
 “General Service Properties” on page 347
 “Run Time Properties for Services” on page 348
 “Transient Error Handling Properties” on page 349
 “Universal Name Properties for Services” on page 355
 “Output Template Properties for Services” on page 355
General Service Properties

In the Properties view, under General, you can assign an ACL to a service. You can also
add a comment to the service.
Permissions Click to assign or view ACL permissions to a service.

Comments Comments about the service.

15 Properties
Run Time Properties for Services

In the Properties view, under Run time, you can specify the following service parameters:
 Caching of service results. You can cache elements to reduce memory usage in
Developer.
Important! The Runtime properties on the Properties view 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.
Stateless Specifies whether or not Integration Server is required to maintain
state information for this service for the duration of the client
session. Select True if the service is a self‐contained, atomic unit of
work and does not need access to state information. This reduces
the number of server resources it consumes at run time. Select False
if the service is part of a multi‐service transaction or if you are
unsure of its state requirements.
The default is False
Cache results Indicates whether Integration Server stores the service results in a
local cache for the time period specified in the Cache expire property.
After the service executes, the server places the entire pipeline
contents into a local cache. When subsequent requests for the
service provide the same set of input values, the server returns the
cached results instead of invoking the service again. Select True to
cache the service results. Select False if you do not want to cache
service results. Cache results for stateless services only.
The default is False.
Note: Caching is only available for data that can be written to the
repository. Because XML nodes cannot be written to the repository,
they cannot be cached.

15 Properties
Cache expire Specifies the amount of time that the pipeline contents stay in

memory after they are cached. If you enable the Cache results
property, type an integer in this field representing the number of
minutes you want a result to remain cached. The expiration timer
begins when the server initially caches the results. The server does
not restart the expiration timer each time it retrieves the results from
cache. The minimum cache expiration time is one minute.
Reset cache Click Reset to clear the cached results for this service
Prefetch Determines whether Integration Server automatically refreshes a
cached result when it expires by re‐executing the service using the
same inputs. To automatically refresh this serviceʹs cached results,
set Prefetch to True. (Prefetch can consume a substantial amount of
server memory; consult your Server Administrator before using this
option.)
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 Integration Server.
Prefetch Specifies the minimum number of times that a cached result must be
activation accessed (hit) with the same inputs in order for the server to
prefetch results when it expires. If you enable Prefetch, you must
specify an integer representing the minimum number of hits a
cached result must receive to be eligible for prefetch. (Entries that
do not receive the minimum number hits are released from
memory.)
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
Execution locale Specifies the locale in which this service will be executed.
Transient Error Handling Properties

When building a service, you can specify what action Integration Server takes when the
service fails because of a transient error caused by a run‐time exception. That is, you can
specify whether or not Integration Server should retry the service.
Integration Server should retry the service.

15 Properties
Max retry Specifies the number of times Integration Server should attempt to

attempts re‐execute the service when the service fails because of an
ISRuntimeException. An ISRuntimeException occurs when the
service catches a transient error, wraps the error, and re‐throws it as
an exception. (A transient error is an error that arises from a
condition that might be resolved quickly, such as the unavailability
of a resource due to network issues or failure to connect to a
database.)
The default is 0, which indicates that Integration Server does not
attempt to re‐execute the service.
Retry interval Specifies the number of milliseconds that Integration Server should
wait between retry attempts. The default is 0 milliseconds, which
indicates that Integration Server re‐executes the service immediately
Note: 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, Integration Server verifies that the retry
period for that service will not exceed the maximum retry period.
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, Designer displays an
error indicating that either the maximum attempts or the retry
interval needs to be modified.
Audit Properties
In the Properties view, under Audit, you enable auditing and specify when a service
should generate audit data.
Enable auditing Specifies when the service generates audit data

Select... To...
Never Indicate that the service should never generate
audit data. Select this option if you do not want to
be able to audit this service.

15 Properties
When top-level Indicate that the service should generate audit data

service only only when it is invoked by a client request or 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 Indicate that the service should generate audit data
every time it executes. Select this option if the
service is a critical service that you want to be able
to audit every time it executes.
Log on Specifies the execution points at which the service generates audit
data.
Select… To…
Error only Indicate that the service should generate audit data

only when the service fails. 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 Indicate that the service should generate audit data
success when the service finishes executing. The service
will generate audit data regardless of whether it
ends because of success or failure. The audit 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.

15 Properties
Error, success, Indicate that the service should generate audit data

and start when it begins executing and when it finishes
executing. The service will generate audit data
twice every time it executes (once when it begins
processing and once when it finishes processing).
Generally, most services execute fairly quickly. By
the time an administrator views the audit log using
webMethods Monitor, the audit log would
probably contain entries for the start and end of
service execution. Situations where you might
want the service to generate audit data at the start
and end of service execution include:
 To check for the start of long‐running services
 To detect service hangs.
In both situations, if service execution began but
did not complete, the audit log contains an entry
for the start of the service, but no entry for the end
of the service.
Performance Impact: Of all the options under Log on,
this option provides the most verbose and
expensive type of audit logging. Every time it
executes, the service generates audit data at two
points: the beginning and the end. Integration
Server must write the audit data to the audit log
twice per service execution. This requires
significantly more disk utilization than the Error
only and Error and success options. At most, the Error
only and Error and success options require
Integration Server to write audit data once per
service execution.
Include pipeline Specifies when Integration Server should include a copy of the input
pipeline in the audit log.

15 Properties
Select… To…
Never Indicate that the input pipeline should never be
included in the audit log. Select this option if you
are using a flat file for the audit log or if you do not
want to be able to resubmit the service to
Integration Server.
Performance Impact: This option requires minimal
network bandwidth because Integration Server
needs to send only the audit data generated by the
service to the audit log.
On errors only Indicate that the input pipeline should be included
in the audit log only when the service ends because
of errors. Select this option if you want to use the
resubmission capabilities of webMethods Monitor
to reinvoke a failed service. For more information
about webMethods Monitor, see the webMethods
Monitor documentation.
Performance Impact: For successful service
invocations, the On errors only option requires
minimal network bandwidth. Service invocations
that end in failure require more network
bandwidth because the Integration Server must
save the audit data and the input pipeline. The
actual network bandwidth needed depends on the
size of the initial input pipeline. A large pipeline
can degrade performance because it may
negatively impact the rate at which the data is
saved to the audit log.

15 Properties
Always Indicate that Integration Server saves a copy of the
input pipeline to the audit log every time the
service generates audit data. If the service
generates data at the start and end of execution
(Log on is set to Error, success, and start), the input
pipeline is saved with the audit log entry for the
start of service execution. If a service does not
generate audit data, 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 Integration Server must write a copy of the
input pipeline to the audit log every time a service
executes. The actual network bandwidth needed
depends on the size of the initial input pipeline. A
large input pipeline can negatively impact the rate
at which the data is saved to the audit log.
Note: If you want audit events generated by this service to pass a copy
of the input pipeline to any subscribed event handlers, select On errors
only or Always.
Important! The options you select can be overwritten at run time by the value of the
watt.server.auditLog server property, set in the server configuration file. This
property specifies whether to globally enable or disable service logging. The default
enables customized logging on a service‐by‐service basis.

15 Properties
Universal Name Properties for Services

You can specify a unique public identifier that external protocols (such as SOAP) use to
reference a service on an Integration Server. Every service on an Integration Server has an
explicit universal name in addition to its regular implicit webMethods name. If you omit
or delete a serviceʹs explicit universal name, it still retains its implicit universal name.
In the Properties view, under Universal Name, you assign a universal name to a service.
Namespace name Specifies the name used to qualify the local name of this service. The

namespace name you specify must be a valid absolute URI (relative
URIs are not supported).
Local name Specifies a name that uniquely identifies this service within the
composed of any combination of letters, digits, or the period (.),
dash (‐), or underscore (_) characters. The name must begin with a
Note: Most webMethods users use the unqualified portion of the
Output Template Properties for Services

In the Properties view, under Output template, you assign can assign an output template to
a service.
Name Specifies the name of the file that contains the output template for
the selected service. To assign an existing template to this service,
type the name of the template file in this field. To create a new
template file for this service, type a name for the template in this
field or accept the name that is suggested by Designer.
Template source Opens the Template source page so that you can edit the existing
output template.
Note: Changes you make to an output template are written to the
template file when you click Save in the Template source page.
Changes that you make to a template file affect all the services in the
package that use the template, not just the service that is currently
open in the editor.

15 Properties
Note: You can only edit an output template in Designer if it one already assigned to
the service. To assign an output template to a service, use Developer.
Transformer Properties
In the Properties view, you can set the properties for a transformer inserted into a MAP
step.
To view properties for a transformer, double‐click the transformer in the Pipeline view of
Designer.
Related Topics
 “General Properties for Transformers” on page 356
General Properties for Transformers

In the Properties view, under General, you can view and configure the service and
validations properties for a transformer.
Service Specifies the fully qualified name of the service that is invoked at
run time. When you insert a transformer, Designer automatically
assigns the name of that service to the Service property.
If the service that a transformer invokes is moved, renamed, or
deleted, you must change the Service property. Specify the service’s
fully qualified name in the folderName:serviceName format or click
to select a service from a list.
Validate input Specifies whether or not the Integration Server validates the input to
the transformer against the input signature of the service. Select True
if you want to validate the input of the service. Select False if you do
not want to validate the input of the service.
Validate output Specifies whether or not the Integration Server validates the output
of the transformer against the output signature of the service. Select
True if you want to validate the output of the service. Select False if
you do not want to validate the output of the service.
Variable Properties
You can specify the data type and input values for a variable. You can also apply content
constraints and structural constraints to a variable for validation purposes. A variable can
be a String, String list, String table, document, document list, document reference,
document reference list, Object, or Object list.

15 Properties
In the Properties view, select a variable in the editor to set general properties and
constraints for the variable.
Note: Specific properties in the Properties view are enabled or disabled, depending on
the type of variable you have selected.
General Properties for Variables

In the Properties view, under General, you can change the data type for a variable. You
can also associate the variable with an XML namespace and specify input values and an
input method.
Name Specifies the name of the variable. To change the name of a variable,
rename it in the editor.
Type Specifies the data type of the variable.
XML namespace Specifies the XML namespace to which the variable belongs.
Comments Specifies a comment about the variable.
String display Specifies how you want to enter input data for this variable. You can
type only select a display type if the variable is a String. Select one of the
following:
Select… To…
Text Field Enter the input in a text field.

Password Enter the input as a password, where
asterisks indicate the input instead of
characters.
Large Editor Enter the input in a large text area instead
of a text field. This is useful if you expect a
large amount of text as input for the
variable, or if you need to have TAB or
new line characters in the input.
Pick List Limit the input to a predefined list of
values. These values appear as choices
when Designer prompts for input at run
time. Click the Pick list choices property’s
Edit button to specify the list of values you
want users to select from.
Pick list choices Allows you to enter the list of values that users can select for this
variable.

15 Properties
Document For a document reference or document reference list, this property
reference specifies the fully qualified name of the document type in the
Package Navigator view that the variable references.
Substitution If the variable represents an element that is a member of a
group substitution group, identifies the head element for which this
element can be substituted.
Constraints Properties for a Variable

Use these properties to apply structural and content constraints to the variable. You only
need to specify constraints if you plan to use this variable with validation.
Required Specifies whether or not the variable needs to exist at run time.
Select... To...
True The default value. Specifies that the variable
must exist in the pipeline at run time.
False Specifies that the existence of the variable is
optional at run time.
Allow null Specifies whether null is a valid value for this variable.
Select... To...
True The default value. Specifies that a null value will
not result in a validation error at run time.
False Specifies that a null value will cause a validation
error at run time.
Allow unspecified Specifies whether the document is open or closed. This property is
fields enabled only if the variable is a document or document list.
Select... To...
True The default value. The document is considered
open. At run time, fields that exist in the
document but are not declared in the document
field will not cause errors.
False The document or document list is considered
closed. At run time, fields that exist in the
document but are not declared in the document
field will be treated as errors.

15 Properties
Content type Specifies the XML schema simple type that constrains the value of

the String field. This property is enabled if the variable is a String,
String list, or String table.
To view and edit the content constraint for a variable, click and
select one of the following:
Select… To…
Content type Select a content constraint from the drop‐down

menu that corresponds to a simple type built‐in
to XML Schema.
Browse Use a simple type from an IS schema as the
content constraint.
Customize Customize a simple type by modifying the
constraining facets.
Base constraints View the constraining facet values set in the type
definitions from which a simple type was
derived.
Java wrapper Specifies the Java class of an Object field. This property is enabled if
type the variable is an Object or Object list.
Constraints Applied to Variables

Designer displays small symbols next to a variable icon to indicate the constraints
applied to the variable. Designer displays variables in the following ways:
Variable Constraint status Variable Properties

Required field. The Required property is set to
True.
Optional field. The Required property is set to
False.
Required field with content The Content type property
type constraint specifies an IS schema or XML
schema.
Optional field with content The Required property is set to
type constraint False and the Content type
property specifies an IS schema or
XML schema.

15 Properties
Note: Designer displays the ‡ symbol next to String, String list, and String table variables
with a content type constraint only. Designer 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 386.
Web Service Connector Properties

To view properties for a Web service connector, double‐click the Web service connector in
the Package Navigator of Designer. In the Properties view, under Web Service Properties,
you can configure the Runtime, Universal Name, Audit, and Output Template properties for the
service.
To edit the properties for a Web service connector, you must have Write access to it and
own the lock.
Related Topics
 “Run Time Properties” on page 360
 “Output Template Properties” on page 364
General Properties
In the Properties view, under General, you can assign an ACL to a Web service connector.
You can also add a comment to the service.
Permissions Click to assign ACL permissions to a service.

Comments Comments about the service.
Run Time Properties

In the Properties view, under Run time, you can specify the following Web service
connector parameters:
 Caching of service results. You can cache elements to reduce memory usage in
Developer.

15 Properties

Important! The Run time properties in the Properties view 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.
Stateless Specifies whether or not Integration Server is required to maintain
state information for this service for the duration of the client
session. Select True if the service is a self‐contained, atomic unit of
work and does not need access to state information. This reduces
the number of server resources it consumes at run time. Select False
if the service is part of a multi‐service transaction or if you are
unsure of its state requirements.
The default is False
Cache results Indicates whether Integration Server stores the service results in a
local cache for the time period specified in the Cache expire property.
After the service executes, the server places the entire pipeline
contents into a local cache. When subsequent requests for the
service provide the same set of input values, the server returns the
cached results instead of invoking the service again. Select True to
cache the service results. Select False if you do not want to cache
service results. Cache results for stateless services only.
The default is False.
Note: Caching is only available for data that can be written to the
repository server. Because XML nodes cannot be written to the
repository, they cannot be cached.
Cache expire Specifies the amount of time that the pipeline contents stay in

memory after they are cached. If you enable the Cache results
property, type an integer in this field representing the number of
minutes you want a result to remain cached. The expiration timer
begins when the server initially caches the results. The server does
not restart the expiration timer each time it retrieves the results from
cache. The minimum cache expiration time is one minute.
Reset cache Click Reset to clear the cached results for this service

15 Properties
Prefetch Determines whether Integration Server automatically refreshes a
cached result when it expires by re‐executing the service using the
same inputs. To automatically refresh this serviceʹs cached results,
set Prefetch to True. (Prefetch can consume a substantial amount of
server memory; consult your Server Administrator before using this
option.)
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 Integration Server.
Prefetch Specifies the minimum number of times that a cached result must be
activation accessed (hit) with the same inputs in order for the server to
prefetch results when it expires. If you enable Prefetch, you must
specify an integer representing the minimum number of hits a
cached result must receive to be eligible for prefetch. (Entries that
do not receive the minimum number hits are released from
memory.)
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
Execution locale Specifies the locale in which this service will be executed.
Audit Properties
In the Properties view, under Audit, you enable auditing and specify when a service
should generate audit data.
Enable auditing Specifies when the service generates audit data

Select... To...
Never Indicate that the service should never generate
audit data.
When top-level Indicate that the service should generate audit
service only data only when it is invoked by a client request
or a trigger.
Always Indicate that the service should generate audit
data every time it executes.

15 Properties
Log on Specifies the execution points at which the service generates audit
data.
Select… To…
Error only Indicate that the service should generate audit

data only when the service fails.
Error and success Indicate that the service should generate audit
data when the service finishes executing. The
service will generate audit data regardless of
whether it ends because of success or failure.
Error, success, and Indicate that the service should generate audit
start data when it begins executing and when it
finishes executing. The service will generate
audit data twice every time it executes (once
when it begins processing and once when it
finishes processing).
Include pipeline Specifies when Integration Server should include a copy of the input
pipeline in the audit log.
Select… To…
Never Indicate that the input pipeline should never be
included in the audit log.
On errors only Indicate that the input pipeline should be
included in the audit log only when the service
ends because of errors.
Always Indicate that the input pipeline should always
be included in the audit log.
Note: If you want audit events generated by this service to pass a
copy of the input pipeline to any subscribed event handlers, select
On errors only or Always.
Important! The options you select can be overwritten at run time by the value of the
watt.server.auditLog server property, set in the server configuration file. This
property specifies whether to globally enable or disable service logging. The default
enables customized logging on a service‐by‐service basis.

15 Properties
Universal Name Properties

Specifies a unique public identifier that external protocols (such as SOAP) use to
reference a service on an Integration Server. Every service on an Integration Server has an
explicit universal name in addition to its regular implicit webMethods name. If you omit
or delete a serviceʹs explicit universal name, it still retains its implicit universal name.
Namespace name Specifies the name used to qualify the local name of this service. The

namespace name you specify must be a valid absolute URI (relative
URIs are not supported).
Local name Specifies a name that uniquely identifies this service within the
composed of any combination of letters, digits, or the period (.),
dash (‐), or underscore (_) characters. The name must begin with a
Note: Most webMethods users use the unqualified portion of the
Output Template Properties

In the Properties view, under Output template, you can assign an output template to a Web
service connector.
Name Specifies the name of the file that contains the output template for
the selected service. To assign an existing template to this service,
type the name of the template file in this field. To create a new
template file for this service, type a name for the template in this
field or accept the name that is suggested by Designer.
Template source Opens the Template source page so that you can edit the existing
output template.
Note: Changes you make to an output template are written to the
template file when you click Save in the Template source page.
Changes that you make to a template file affect all the services in the
package that use the template, not just the service that is currently
open in the editor.

15 Properties
Note: You can only edit an output template in Designer if it is already assigned to the
service. To assign an output template to a service, use Developer.
Web Service Descriptor Properties

To view properties for a provider or consumer Web service descriptor, double‐click the
Web service descriptor in Package Navigator view of Designer.
Related Topics
 “Web Service Descriptor Operation Properties” on page 366
 “Fault Element Properties” on page 368
 “Binder Properties” on page 368
 “Web Service Descriptor Header Handler Properties” on page 370
General Properties
In the Properties view, under General, you can view and assign properties to a Web
service descriptor.
Name Displays the name of the Web service descriptor.
Direction Displays whether the Web service descriptor is for a provider Web
service (that can be invoked by an external user) or for a consumer
Web service (that requests the use of a provider entityʹs Web
service).
WS-I compliance Specifies whether the Web service descriptor enforces compliance
with the WS‐I Basic Profile 1.1 standards.
Target Displays the XML Target Namespace of the Web service. By default
namespace this is set to the fully qualified URL of the host server.
WSDL URL URL used to retrieve the WSDL for the Web service.
Namespaces Displays a list of the XML namespaces used within the document.
This is an array of Namespace Prefixes and their associated XML
Namespace names.
Attachment Specifies whether any attachment should be enabled. The default is
enabled False.

15 Properties
Web Service Descriptor Operation Properties

The Properties view displays basic information about the Web service operation (or about
the header, body, and fault documents) when the operation or one of its documents is
selected in the Web service descriptor editor.
Note: Selecting the Response or Request element in an operation simply displays the
properties for the operation as a whole. You must select the individual Header, Body,
or Fault to display its properties.
Related Topics
 “Operation Properties” on page 366
 “Body Element Properties” on page 366
 “Header Element Properties” on page 367
Operation Properties
In the Properties view, under General, you can view basic information about an operation
in the Web service descriptor.
Operation Name Displays the name of the operation. For a provider Web service

descriptor, this will be the local portion of the Universal Name of
the IS service. For a consumer Web service descriptor, this will be
the operation Name from the WSDL that was used to create the Web
service descriptor.
IS Service Displays the fully‐qualified name of the IS service representing this
operation.
Body Element Properties

In the Properties view, under General, you can view basic information about the Body
element in an operation’s request or response. None of the properties of a Body element
can be modified.
Name Name of the Body element.
Document type Fully‐qualified name of the IS Document type that defines the body.
Namespace Namespace owner of the Body element.
owner
Signature type Signature type of the Body element.
Schema URL Schema URL, if the signature is from a schema.

15 Properties
Schema element Schema element if the signature is from a schema.

Signature The constraint type on the Input/output signature of the Web
service descriptor. The default setting is Original IS service. This
option can be changed to Existing external Schema in a provider Web
service descriptor that was generated from an existing IS service.
Depending on the protocol you select, you may need to select an IS
document type or XML Schema component to represent the input
and/or output signature of the service.
Header Element Properties

In the Properties view, under General, you can view basic information about a header
element in an operation’s request or response.
Name Displays the name of the Header element.
Document type Displays the fully‐qualified name of the IS Document type that
defines the Header element.
Must understand Indicates whether the Header element must be understood by the
SOAP node in order for the message to be processed.
“Must Understand” is a SOAPHeader attribute. If MustUnderstand
is set and the SOAP Node Receives a Header that it does not
understand, it must not process the SOAP Request and the SOAP
Node must return a “Not Understood” Fault.
If this attribute is set to True for a consumer Web service descriptor,
the Must Understand attribute of the Header is set to true in the
request.
Role URI naming the Actor (for SOAP 1.1) or Role (for SOAP 1.2) at
which this header element is targeted. A Header is “targeted” at a
SOAP Node if the node is acting in the role specified on that Header.
The possible values are defined by the SOAP Specification.

15 Properties
Fault Element Properties

In the Properties view, under General, you can view basic information about a fault
element in an operation’s response.
General Properties
In the Properties view, under General, you can view basic information about a Fault
element in an operation’s request or response.
Name Displays the name of the Fault element.
Document type Displays the fully‐qualified name of the IS Document type defining
the Fault element.
Binder Properties
In Properties view, you can view basic information about the binder for a Web service
descriptor when you select a binder in Binders tab in the Web services descriptor editor.
General Properties
In the Properties view, under General, you can view basic information about the binder
for the Web service descriptor.
Binder name Name of the IS binder.

Port address Endpoint address associated with this Web service, that is, the
network address at which the Web service can be invoked.
Port alias Endpoint alias name associated with this Web service. The Endpoint
alias name will be used for this binder when generating a WSDL for
a provider or when executing a Web service connector for a
consumer. The actual Endpoint value is looked up at runtime in
both cases. New aliases can be defined from the Integration Server,
using Settings > Web Services.
Port name Name of the port associated with the Web service, as defined by the
WSDL; an aggregate of a binding and a network address.
Directive The SOAP processor for which the Web service will be a target. The
drop‐down menu lists all registered SOAP processors on the
Integration Server to which you are currently connected. For
information about creating and registering your own SOAP
processor, see the SOAP Developer’s Guide.
Binding name Name of the WSDL binding element.

15 Properties
Porttype name Name of the portType associated with the WSDL binding element.

Binding type Type of binding. Currently, only SOAP over HTTP is supported.
Transport Transport mechanism used to invoke the Web service, either HTTP
or HTTPS. The transport you select must match the type of requests
accepted by the port you selected.
SOAP version Version of the SOAP message protocol to be used; either SOAP 1.1
or SOAP 1.2.
SOAP binding The style of the SOAP binding and its operations; either Document
style or RPC (Remote Procedure Call).
SOAP binding The usage attribute of the SOAP binding and its operations; either
use literal or encoded
SOAP binding The transport protocol used by this SOAP Binding.
transport
SOAP action Value associated with a SOAPAction operation. Used at runtime to
find the actual operation being invoked, but only if SOAP Binding is
in use.
Click the View button to display the SOAPAction string associated
with each Operation in the given Binder.
For provider Web service descriptors these SOAPAction values are
generated into the WSDL for the Binding Operation and at runtime
are expected to be present in the SOAPAction Header on the
inbound Request.
For consumer Web service descriptors these SOAPAction values
will represent the value found in the Binding Operation definition
of the WSDL used to generate the consumer Web service descriptor
and will be placed into the SOAPAction header of the outbound
request.

15 Properties
Web Service Descriptor Header Handler Properties

You can view basic information about the header handlers for the Web service descriptor
in the Properties view.
General Properties
In the Properties view, under General, you can view basic information about the header
handler.
Handler name Name of the header handler.

Class name The Java class name of the JAX‐RPC handler that acts as the header
handler.
Policy type The policy type associated with the header handler. Policy files used
with this header handler must be of this type.
Policy name Specifies the name of the policy assigned to this header handler. The
policy name is obtained from the ID attribute in the policy file. At
run time, the assigned policy can be overridden by the value of the
Effective policy name property.
Effective policy Specifies the name of the policy used with this header handler at
name run time. The effective policy overrides the policy assigned in the
Policy name property

16 webMethods Flow Steps
 “BRANCH” on page 371
 “EXIT” on page 374
 “INVOKE” on page 375
 “LOOP” on page 376
 “MAP” on page 378
 “REPEAT” on page 379
 “SEQUENCE” on page 382
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.
Related Topics
 “Branching on a Switch Value” on page 371
 “Branching on Expressions” on page 372
 “Conditions that Will Cause a BRANCH Step to Fail” on page 373
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
Name2
if the value of choice is
Name of the
switch field is NameN
choice if the value of choice is
$null
if choice does not exist or has
a value of ‘$null’
no
if the value of choice is an
empty string “ “
$defaul
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
Child2
if the expression of second child is true
Evaluate
labels is set to
true ChildN
if the expression of nth child is
$defau
Otherwise

BRANCH 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, the server
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Label Optional. (Required if you are using this BRANCH step as a target for
another BRANCH or EXIT step.) Specifies a name for this instance of
the BRANCH step, or a null, unmatched, or empty string ($null,
$default, blank).
Switch Specifies the String field that the BRANCH step uses to determine
which child flow step to execute. The BRANCH step executes the child
flow step whose label matches the value of the field specified in the
Switch property. Do not specify a value if you set the Evaluate labels
property to True.
Evaluate 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.
Related Topics
 “Examples of When to Use” on page 375
EXIT 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%.
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.
Related Topics
 “Conditions that Will Cause an INVOKE Step to Fail” on page 376
INVOKE Properties
The INVOKE step has the following properties.
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.

If you want to use the value of a pipeline variable for this property,
type the variable name between % symbols. For example,
%expiration%.
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
Related Topics
 “Conditions that Will Cause a LOOP Step to Fail” on page 378
LOOP Properties
The LOOP step has the following properties.
pipeline to which you want to restrict this step. If you want this step to
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.
Related Topics
 “Example of When to Use” on page 379

MAP 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, the server waits for the
step to complete and then raises an exception.
Label Optional. (Required if you are using this step as a target for a BRANCH or
EXIT step.) Specifies a name for this specific step, or a null, unmatched, or
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.
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 No
interval met?
No
Exit
Related Topics
 “When Does REPEAT Fail?” on page 381
 “Examples of When to Use” on page 381
REPEAT 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
to the entire pipeline, leave this property blank.
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).

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%.
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%.
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 If exit
First... condition is condition is
child child child
Related Topics
 “Conditions that Will Cause an INVOKE Step to Fail” on page 376
SEQUENCE 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.

If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%.
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
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:

17 Supported Data Types
 “Data Types” on page 385
 “How Designer Supports Tables” on page 388
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 Designer.
Data Type Icon Description Java Class

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 variables.
com.wm.util.Values
Documents can contain
variables of any other data For more information, see
type. The contents of a the webMethods Integration
document (IData object) are Server Java API Reference.
stored as key/value pairs
where the variable name is
the key.
Document list A one‐dimensional array of com.wm.data.IData [ ]
IS document types (IData [
com.wm.util.Values [ ]
]or Values [ ]).
com.wm.util.Table


Document A document whose structure Reference to an existing
reference is defined by an IS document object which implements
type. the 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
reference list structure is defined by an IS object which implements
document type. the com.wm.data.IData
interface or a reference to
an existing
com.wm.util.Values object.
Object A data type that does not fall Any subclass of
into any of the data types java.lang.Object.
described in the above rows,
Example:
and is not declared to be one
java.util.InputStream
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.util.InputStream[ ]
Note: Designer displays small symbols next to a variable icon to indicate validation
constraints. Designer uses to indicate an optional variable and the ‡ symbol to
denote a variable with a content constraint.
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, Designer 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 running and debugging.

 You can assign values to variables in the pipeline using on the Pipeline view
toolbar..
Note: When you input values for a constrained Object during debugging or when
assigning a value in the pipeline, Designer 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 Designer.

boolean True or false. java.lang.Boolean
boolean list A one‐dimensional boolean java.lang.Boolean[ ]

array.
byte Signed integer. The value java.lang.Byte
must be 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 java.lang.Double

point number.
double list A one‐dimensional double java.lang.Double[ ]
array.
float Standard‐precision floating java.lang.Float
point number.
float list A one‐dimensional float array. java.lang.Float[ ]
integer Signed integer. The value java.lang.Integer

to ‐2147483647 but less than
or equal to 2147483647.


integer list A one‐dimensional integer java.lang.Integer[ ]
array.
long Signed integer. The value java.lang.Long
to
–9223372036854775808 but less
than or equal to
9223372036854775807.
long list A one‐dimensional long array. java.lang.Long[ ]
short Signed integer. The value java.lang.Short

to ‐32768 but less than or equal
to 32767.
short list A one‐dimensional short java.lang.Short[ ]
array.
How Designer Supports Tables

With the exception of String table, Designer 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 Designer. 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.

18 Icons
18 Icons
 “Package Navigator View Icons” on page 389
 “UDDI Registry View Icons” on page 392
 “Flow Step Icons” on page 393
Package Navigator View Icons

The following icons are used to represent elements in the Package Navigator view.
This icon... Represents...

A server. You can have multiple server contexts displayed in Designer. The
active server context is the one that is highlighted in Package Navigator
view. 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.
Note: Designer places Trading Networks document types in a package
named “Trading Networks Documents”.
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 Java service. A Java service is a service written in Java.
A C service. A C service is a service written in C/C++.
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.

18 Icons

A specification. A specification is a formal description of a service’s inputs
and outputs.
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.
A Broker/local trigger. A Broker/local trigger is trigger that subscribes to and
processes documents published/delivered locally or to the Broker.
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.
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. Designer automatically
generates a Web service connector when it creates a Web service
descriptor for a consumer Web service. Designer can also create a Web
service connector from an existing WSDL.
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.
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.
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.

18 Icons

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.
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.
An XSLT service. An XSLT service converts XML data into other XML
formats or into HTML, using rules defined in an associated XSLT
stylesheet.
A Blaze rule service. A rule deployed to Integration Server by Blaze
Advisor. Integration Server generates them as rule services and executes
them at run time.
A Trading Networks document type. You can drag and drop a Trading
Networks (TN) document type into a process model. The “drop” creates a
Receive step in the process, with the subscription set to the TN document
type name.
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.
Related Topics

18 Icons
UDDI Registry View Icons

The UDDI Registry view 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. Designer displays the URL of the UDDI Registry to
which you are connected next to the registry icon. Below the UDDI
Registry name, Designer 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, Designer 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. Designer 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.
Related Topics

18 Icons
Flow Step Icons

A flow step is a basic unit of work (expressed in the webMethods flow language) that
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.
The following table identifies the flow step icons that you can use when building flow
service.
Icon Step Description

INVOKE Executes a specified service.
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).
BRANCH Executes a specified flow step based on the value of a
specified variable in the pipeline.
LOOP Executes a set of flow steps once for each element in a
specified array.
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.
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.
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).
Related Topics

18 Icons

19 Toolbars
19 Toolbars
 “Document Type Editor Toolbar” on page 395
 “Flow Service Editor Toolbar” on page 396
 “Package Navigator View Toolbar” on page 398
 “Service Result View Toolbar” on page 400
 “UDDI Registry View Toolbar” on page 401
 “Variables View Toolbar” on page 401
 “Web Service Descriptor Editor Toolbar” on page 402
Document Type Editor Toolbar

The following buttons appear on the document type editor toolbar.
Button Description
Reverses the previous action. Equivalent to Edit > Undo.
Repeats the previous action. Equivalent to Edit > Redo.
Cuts elements. Equivalent to Edit > Cut.
Copies elements. Equivalent to Edit > Copy.
Pastes elements after performing a copy or cut. Equivalent to Edit > Paste.
Deletes the selected variable. If you select a variable that has children, the
children are deleted as well. Equivalent to Edit > Delete.
Moves the selected variable up one position. If the selected variable
cannot be moved up from its current position, this button is not available.
(Try promoting or demoting it first.)
Moves the selected variable down one position. If the selected variable
cannot be moved down from its current position, this button is not
available. (Try promoting or demoting it first.)
Promotes the selected variable one position to the left. You use this button
to move a variable out of a document or document list. If the variable
cannot be shifted left from its current position, this button is not available.

19 Toolbars
Button Description
Demotes the selected variable one position to the right. You use this
button to make a variable a member of a document or document list. If
the variable cannot be shifted right from its current position, this button is
not available.
Displays a list of data types that you can use to create variables for the
document type. To create a variable for the document type, select the
appropriate data type from this list, and then give the new variable a
name.
Related Topics
Flow Service Editor Toolbar

The following buttons that are unique to Designer appear on the flow service editor
toolbar.
Button Description
Deletes the selected flow step. If you select a step that has children, the
children are deleted as well. Equivalent to Edit > Delete.
Moves the selected flow step up in the list. If the selected step cannot be
moved up from its current position, this button is not available. (Try
promoting or demoting it first.)
Moves the selected flow step down in the list. If the selected step cannot
be moved down from its current position, this button is not available. (Try
promoting or demoting it first.)
Promotes a flow step in the parent/child hierarchy. This action moves the
step up one level in the hierarchy.

19 Toolbars
Button Description
Demotes a flow step in the parent/child hierarchy. This action makes the
selected step a child of the preceding parent step. (This button is only
available when you select a step that can become a child.)
Inserts the previously inserted flow step.
Click the button next to to view the list of flow steps and a list of

commonly used services that can be inserted into the flow service as an
INVOKE step. You can edit the Window > Preferences > Software AG > Service
Development > Flow Service Editor preferences to customize this list of
services to suit your needs.
Inserts a MAP step into the flow service. A MAP step performs specified
editing operations on the pipeline (for example, adding or dropping
variables to or from the pipeline).
Inserts a BRANCH step into the flow service. A BRANCH step executes a
specified step based on the value of a specified variable in the pipeline.
Inserts a LOOP step into the flow service. A LOOP step executes a set of
steps once for each element in a specified array.
Inserts a REPEAT step into the flow service. A REPEAT step re‐executes a
set of steps up to a specified number of times based on the successful or
non‐successful completion of the set.
Inserts a SEQUENCE step into the flow service. A SEQUENCE step
groups a set of steps into a series. The SEQUENCE step is implicit in most
cases where a group of flow steps are listed one after another. However, it
is often useful to explicitly insert the SEQUENCE step to override default
operating parameters. It is also useful for setting up the branches of a
BRANCH step.
Inserts an EXIT step into the flow service. An EXIT step controls the
execution of a flow steps; for example, halt an entire flow 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.
Inserts an INVOKE step into the flow service. Select from the displayed
list of services or browse to select a service.
Related Topics

19 Toolbars
 “Building Flow Services” on page 155
Package Navigator View Toolbar

The following buttons appear on the Package Navigator view toolbar.
Button Description
Collapses all of the expanded Integration Servers in Package Navigator
view.
Opens the editor for the selected element in Package Navigator view.
Filters the contents of Package Navigator view by displaying elements of
a specified type only.
Opens Integration Servers preferences where you can add, edit, or
remove Integration Server definitions.
Sorts the contents of Package Navigator view alphabetically by name or
alphabetically by element type.
Related Topics
 “Working with Elements” on page 33
 “Working with webMethods Integration Server” on page 19

19 Toolbars
Pipeline View Toolbar

The following buttons appear on the Pipeline view toolbar.
Button Description
Creates a link between the variables in the pipeline. Links can be
created between variables in Pipeline In and Service In, or between Service
Out and Pipeline Out. In a MAP step, links can be created between
variables in Pipeline In and Transformers, or between Transformers and
Pipeline Out. To link a variable from one stage to another, select the two
variables, and then click the link button. This button is not available
unless you select two variables that can be linked successfully.
Assigns a value to the selected variable in the Service In or Pipeline Out
stage.
Drops the selected variable from the pipeline. You may remove a
variable from the Pipeline In or Pipeline Out stage. When you drop a
variable, that variable is removed permanently from the pipeline and is
not available to subsequent services in the flow.
Adds a new variable to the selected stage in the pipeline. This is a useful
way to create a variable that is used by a service in a flow (that is, taken
as input or produced as output), but was omitted from the input/output
signature.
Moves the selected variable up one position. If the selected variable
cannot be moved up from its current position, this button is not
Moves the selected variable down one position. If the selected variable
cannot be moved down from its current position, this button is not
Promotes the selected variable one position to the left. If the variable
cannot be shifted left from its current position, this button is not
available.
Demotes the selected variable one position to the right. If the variable
cannot be shifted right from its current position, this button is not
available.
Inserts a service for use as a transformer in a MAP step. This feature is
only available when a MAP step is selected in the editor.
Related Topics

19 Toolbars
Service Result View Toolbar

The following buttons appear on the Service Result view toolbar.
Button Description
Goes to the flow step at which an error occurred while running or
debugging a flow service.
Saves the service results pipeline to a file in your local file system.
Saves the service results pipeline to the
IntegrationServer_directory\pipeline directory on the machine that hosts
Integration Server.
Restores the pipeline contents from a file on your local file system.
Restores the pipeline contents from the
Integration Server.
Related Topics

19 Toolbars
UDDI Registry View Toolbar

The following buttons appear on the UDDI Registry view toolbar.
Button Description
Connect to a UDDI Registry while working in Designer.
Disconnect from a UDDI Registry while working in Designer.
Refresh the display of Web services.
Create an expression that filters the contents of the UDDI Registry view
based on the value of a Web service property.
Remove the filter from the contents of the UDDI Registry view and
display all the published Web services.
Create a Web service descriptor (WSD) from the Web service selected in
the UDDI Registry view.
Related Topics
Variables View Toolbar

The following buttons that are unique to Designer appear on the Variables view toolbar.
Button Description
Drop a selected variable from the pipeline passed to the next step in a
debugging session.
Deletes a row in a table for the selected variable.
Saves the pipeline as an XML document to your local file system..

19 Toolbars
Button Description
Loads a pipeline from a local file. The pipeline you load completely
replaces the current debugging pipeline.
Saves the pipeline as an XML file on in the
the Integration Server.
Loads a pipeline from a file in the IntegrationServer_directory\pipeline
directory on the machine that hosts the Integration Server.
Related Topics
Web Service Descriptor Editor Toolbar

The following buttons appear on the Web Service Descriptor (WSD) editor toolbar.
Button Description
Adds one or more operations to a Web service descriptor.
Enabled only for provider Web service descriptors created from an
Integration Server service (in other words, you cannot add an operation
to a consumer Web service descriptor or a provider Web service
descriptor created from a WSDL URL or a UDDI Registry). The operation
is added to the view in the Operations area as well as the Binders tab.
Adds a binder definition (SOAP/Transport/Use‐Style) to a Web service
descriptor.
Enabled only for provider Web service descriptors created from an
Integration Server service (in other words, you cannot add a binder
definition to a consumer Web service descriptor or a provider Web service
descriptor created from a WSDL URL or a UDDI Registry). All existing
operations are duplicated within the new binder.

19 Toolbars
Button Description
Adds a header or fault element to a Request or Response.
If a fault element is selected when you click this button, the default
Designer document selector dialog enables you to add a document for the
fault.
If a header element is selected when you click this button, a special
document selector displays only those document types supported by the
header handlers listed in the Handler tab.
Add a header handler to a Web service descriptor.
Opens a drop‐down list of the existing header handlers. The selected
handler is added to the top of the list.
Analyze Web service descriptor for WS I conformance.
Regenerate the specified Web service connectors.
Enabled only for consumer Web service descriptors. When no operations
are selected, this button refreshes (regenerates) all Web service connectors
in the Web service descriptor. When one or more operations are selected,
only the Web service connectors for the selected operations are refreshed.
This process overwrites existing Web service connectors.
Related Topics

19 Toolbars

20 Supported and Unsupported Elements in
webMethods Designer
 “Supported Elements” on page 405
 “Unsupported Elements” on page 405
Supported Elements
Designer provides support for the following elements originally in webMethods
Developer.
 Document types
 Flow services
 JMS triggers
 Web service connectors
 Web service descriptors
Related Topics
 “Unsupported Elements” on page 405
Unsupported Elements
Designer does not yet provide full support for the following elements from webMethods
Developer. While you can perform some basic tasks such as moving, copying, renaming,
or deleting, Designer cannot be used to create or modify these elements. To create or
modify any of the elements listed below, use webMethods Developer.
 Adapter services or adapter notifications
 Broker/local triggers
 C services
 Connections
 Flat file dictionaries or flat file schemas
 IS schemas
 Java services
 Listeners

20 Supported and Unsupported Elements in webMethods Designer
 .NET services
 Specifications
 XSLT services
Note: While you cannot yet create an IS schema in Designer, any IS schema created
when you use Designer to create an IS document type will appear in Package
Navigator view.
Note: Even though Java services, C/C++ services, and specifications are not fully
supported in Designer Version 7.2, you can view the signature of the services or
specifications. If you double‐click a Java service, C/C++ service, or specification in
Package Navigator view, Designer displays the element signature on the
Input/Output tab for the editor.
Related Topics
 “Supported Elements” on page 405

Webmethods Designer Service Development Help 7 2

Uploaded by

Copyright:

Available Formats

Webmethods Designer Service Development Help 7 2

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

Webmethods Designer Service Development Help 7 2

Uploaded by

Copyright:

Available Formats

Title Page

Document ID: DES-ESBDH-72-20081212

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Part I. Service Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1. Working with webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2. Working with Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

webMethods Designer Service Development Help Version 7.2 3

Configuring Dependency Checking for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3. Assigning and Managing Permissions for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

4 webMethods Designer Service Development Help Version 7.2

4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5. Checking Elements In and Out of a VCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

webMethods Designer Service Development Help Version 7.2 5

Restoring Deleted Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6. Managing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

7. Building Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

6 webMethods Designer Service Development Help Version 7.2

Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

8. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

webMethods Designer Service Development Help Version 7.2 7

The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

9. Mapping Data in Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

8 webMethods Designer Service Development Help Version 7.2

Deleting a Link Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

10. Running and Debugging Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

webMethods Designer Service Development Help Version 7.2 9

Enabling and Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

11. Working With Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

10 webMethods Designer Service Development Help Version 7.2

Editing Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

12. Working with Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Part II. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

13. Integration Server Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

14. Service Development Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

webMethods Designer Service Development Help Version 7.2 11

15. Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

12 webMethods Designer Service Development Help Version 7.2

Web Service Connector Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

16. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

webMethods Designer Service Development Help Version 7.2 13

17. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

18. Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

19. Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

20. Supported and Unsupported Elements in webMethods Designer . . . . . . . . . . . . . . . . 405

14 webMethods Designer Service Development Help Version 7.2

webMethods Central Documentation Directory

webMethods Designer Service Development Help Version 7.2 15

webMethods Advantage Bookshelf

Software AG Developer Community

16 webMethods Designer Service Development Help Version 7.2

webMethods Designer Service Development Help Version 7.2 17

Before You Use Designer for Service Development

18 webMethods Designer Service Development Help Version 7.2

1 Working with webMethods Integration Server

Working with Server Definitions

webMethods Designer Service Development Help Version 7.2 19

Creating Server Definitions

To create a server definition

20 webMethods Designer Service Development Help Version 7.2