webMethods DeveloperUsers Guide
Version 7.1.1
January 2008
webMethods
TitlePage
ThisdocumentappliestowebMethodsDeveloperVersion 7.1.1andwebMethodsIntegrationServerVersion 7.1.1andtoallsubsequentreleases.
Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions.
CopyrightSoftwareAG2008.
Allrightsreserved.
ThenameSoftwareAGand/orallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.Othercompanyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners.
Document ID: DEV-UG-711-20080128
Copyright& DocumentID
Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Getting Started with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
The Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Navigation Panel Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Refreshing the Contents of the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . 25
The UDDI Registry Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25UDDI Registry Tab Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
The Recent Elements Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27The Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29The Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Moving Between Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Performing Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Resizing Areas in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Hiding and Showing Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Dragging Movable Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Switching Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Restoring a Session on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Notification of Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2. Managing Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
About Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Package Names and Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Guidelines for Naming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Editing Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43webMethods Developer Users Guide Version 7.1.1 3
Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table of Contents
Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Moving and Copying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Copying Elements Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Moving and Copying Adapter Notifications and Related Elements . . . . . . . . . . . . . . . . 49
Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Finding Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Finding Fields in Editor Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Locating Invoked Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Finding Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Finding References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Clearing the Developer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3. Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Guidelines for Naming Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Viewing Details for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Optimizing Lock Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Copying a Package to Another Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Documenting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Exporting a Package or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Assigning a Version Number to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Viewing the Patch History for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Identifying Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Removing Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83What Is a Shutdown Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Guidelines for Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . 85Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . 85Removing Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . 864 webMethods Developer Users Guide Version 7.1.1
Table of Contents
4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88How Do I Know Who Has an Element Locked? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89When Do I Lock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89When Do I Unlock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Unlocking Elements Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Unlocking an Element Using the Integration Server Administrator . . . . . . . . . . . . . . . . 95Unlocking a System Locked Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Viewing an Elements Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . . 98Automatically Unlocking Elements After Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Lock/Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5. Assigning and Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
What Is an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104What Happens When a Client Runs a Service with ACLs? . . . . . . . . . . . . . . . . . . . . . 104Am I Required to Use ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106How Do I Create an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106The Permissions Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Default ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ACLs and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111ACLs and Testing/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . 112
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112webMethods Developer Users Guide Version 7.1.1 5
Table of Contents
6. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
What Is a Flow Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117What Is the Pipeline? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118What Are Input and Output Parameters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Package and Folder Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Using the Default Logic Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Specifying Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Specifying Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Completing the Input/Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Maintaining the State of a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Configuring a Services Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Types of Services to Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Services Suited for Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Services that You Should Not Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Controlling a Services Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Specifying the Duration of a Cached Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Using the Prefetch Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Specifying the Execution Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Assigning Universal Names to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Enabling Auditing for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Specifying When Audit Data Is Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Including the Pipeline in the Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
When Is a Copy of the Input Pipeline Saved in the Audit Log? . . . . . . . . . . . . . . . 144Service Auditing Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Error Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Auditing for Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Auditing Long-Running Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Setting Auditing Options for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Audit Level Settings in Earlier Versions of Developer . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496 webMethods Developer Users Guide Version 7.1.1
Table of Contents
7. Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Changing the Position of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Changing the Level of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Setting the Properties of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Specifying the Service Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Invoking a Built-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Invoking a Service on Another webMethods Integration Server . . . . . . . . . . . . . . . . . . 158Building an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Specifying the Switch Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Specifying the Label Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Branching on an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Branching on Null and Empty Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Specifying a Default Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Using SEQUENCE as the Target of a BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Building a BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Specifying the REPEAT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Setting the REPEAT Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Using REPEAT to Retry a Failed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Using REPEAT to Retry a Successful Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Using SEQUENCE to Specify an Exit Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Specifying the Input Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Collecting Output from a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Building a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
8. Mapping Data in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Pipeline Tab for an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Pipeline Tab for a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Pipeline Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Printing the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Linking Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
What Happens When Integration Server Executes a Link Between Variables? . . 196webMethods Developer Users Guide Version 7.1.1 7
Table of Contents
Linking to Document and Document List Variables . . . . . . . . . . . . . . . . . . . . . . . . 198Linking Variables of Different Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Examples of Structural Transformations on the Pipeline Tab . . . . . . . . . . . . 200Converting a String List to a Document List . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Guidelines for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . 203
Deleting Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Applying Conditions to Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Linking Multiple Source Variables to a Target Variable . . . . . . . . . . . . . . . . . 205Assigning Values to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Assigning a Default Value to a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Initializing Variables in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Referencing Other Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Setting a Value for a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Copying Set Values Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Dropping Variables from the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Adding Variables with the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212What Are Transformers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Using Built-in Services as Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Inserting a Transformer into a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Linking Variables to a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Transformer Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Transformers and Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
What Is Dimensionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Validating Input and Output for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Copying Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Expanding Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Renaming Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Debugging Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . . . . . . . . 223Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
What Does an IS Schema Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Schema Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Schema Details Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Creating IS Schemas from XML Schemas that Reference Other Schemas . . . . . 230Editing a Simple Type in an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Setting Constraining Facet Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . . 2358 webMethods Developer Users Guide Version 7.1.1
Table of Contents
Points to Consider for All Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Points to Consider When Using a DTD As the Source . . . . . . . . . . . . . . . . . . . . . 236Points to Consider When Using an XML Schema As the Source . . . . . . . . . . . . . 236
Expanding Complex Document Types Inline . . . . . . . . . . . . . . . . . . . . . . . . . 237Generating Fields for Substitution Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Creating an IS Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . 240The Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . 243
Editing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Printing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Using an IS Document Type to Specify Service Input or Output Parameters . . . . . . . 245Using an IS Document Type to Build a Document Reference or Document Reference List
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Specifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
10. Performing Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
What Is Data Validated Against? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Considerations for Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Customizing a String Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Viewing the Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Specifying Input/Output Validation via the Input/Output Tab . . . . . . . . . . . . . . . . . . . . 261Specifying Input/Output Validation via the INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . 262
Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . 264Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Running Out of Memory During Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
11. Testing and Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Entering Input for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Saving Input Values to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Loading Input Values from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Viewing the Results of the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Copying Variables from the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Run-Time Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277webMethods Developer Users Guide Version 7.1.1 9
Table of Contents
The Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278The Pipeline Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Entering Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Combining the Step and Trace Commands in Debug Mode . . . . . . . . . . . . . . . . . . . . 283Resetting Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Using the Trace Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Tracing into a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Using the Step Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Stepping though a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Using the Step Tools with a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288What Happens When a Breakpoint Is Encountered? . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Setting Breakpoints on Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Viewing a List of Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Disabling Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Disabling Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Disabling a Condition Placed on a Link Between Variables . . . . . . . . . . . . . . . . . . . . . 294
Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Saving the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Saving the Contents of the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Loading a Saved Pipeline into the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . 299Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Using the Servers Debug Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300The Contents of the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Server Debug Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Writing Information to the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Writing an Arbitrary Message to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Dumping the Pipeline to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
12. Building Coded Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
The IData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Services Take IData Objects as Input and Return IData as Output . . . . . . . . . . . 308Getting and Setting Elements in an IData Object . . . . . . . . . . . . . . . . . . . . . . . . . 309Creating IData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31010 webMethods Developer Users Guide Version 7.1.1
Table of Contents
Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Using the Developer IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
The Java Service Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311The Shared Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Creating a Java Service with Developers IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Generating Java Code from Service Input and Output Parameters . . . . . . . . . . . 315
Setting Run-Time Options for a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
The Namespace Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317The Source Code Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Writing the Source Code for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Using the webMethods API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319The Basic Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Commenting Code for the webMethods Integration Server . . . . . . . . . . . . . . . . . 320
Using the jcode Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Make Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Fragment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Composite Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Other jcode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Generating Files for a C/C++ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324The Java Code for a C Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Building the C/C++ Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . 328Creating the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Invoking the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
13. Creating Client Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337webMethods Developer Users Guide Version 7.1.1 11
Table of Contents
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
General Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Files for the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Files Containing the Code that Invokes the Service . . . . . . . . . . . . . . . . . . . . . . . 339File Containing the Code that Interacts with webMethods Integration Server . . . . 339
Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Invoking Services with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Using the HTTP GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Using the HTTP POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Input to the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Output from the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
14. Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
What Are Event Handlers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350What Happens When an Event Occurs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Subscribing to an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Creating Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Creating Event Filters for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Viewing and Editing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Suspending Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Deleting an Event Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Sample Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Building Handlers for Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Building Handlers for Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Building Handlers for Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Guaranteed Delivery Events and Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . 364Building Handlers for Guaranteed Delivery Start Events . . . . . . . . . . . . . . . . . . . . . . . 365Building Handlers for Guaranteed Delivery End Events . . . . . . . . . . . . . . . . . . . . . . . . 366
Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Building Handlers for Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36712 webMethods Developer Users Guide Version 7.1.1
Table of Contents
Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Building Handlers for Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Building Handlers for Session Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Building Handlers for Session End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Building Handlers for Session Expire Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370Building Handlers for Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372Building Handlers for Transaction Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372Building Handlers for Transaction End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
15. Building Services that Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Adapter Services and Retry Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
How to Build a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . 377ExampleBuilding a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . 380
A. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Branching on Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Conditions that Will Cause a BRANCH Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Conditions that Will Cause an INVOKE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389Conditions that Will Cause a LOOP Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Example of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Conditions that Will Cause the SEQUENCE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . 395webMethods Developer Users Guide Version 7.1.1 13
Table of Contents
B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
C. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Java Classes for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407How webMethods Developer Supports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . 409
D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Comparing Java Objects to Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Checking for Variable Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Standard Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Lexical Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Addressing Variables that Contain Special Characters . . . . . . . . . . . . . . . . . . . . . . . . 426Typing Special Characters in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Sample CodeIData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
F. Validation Content Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
G. Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47514 webMethods Developer Users Guide Version 7.1.1
About This Guide
ThisguidedescribeshowtocreateservicesusingwebMethodsDeveloper.ItcontainsinformationfordeveloperswhowanttobuildservicesusingthewebMethodsflowlanguageoraprogramminglanguagesuchasJava,C/C++,orVisualBasic.
Tousethisguideeffectively,youshouldknowhowtoprograminJava,C/C++,and/orVisualBasicifyouwillbecreatingservicesinthoselanguages.
Document Conventions
Convention Description
Bold Identifieselementsonascreen.Italic Identifiesvariableinformationthatyoumustsupplyorchangebased
onyourspecificsituationorenvironment.Identifiestermsthefirsttimetheyaredefinedintext.Alsoidentifiesserviceinputandoutputvariables.
Narrow font IdentifiesstoragelocationsforservicesonthewebMethodsIntegrationServerusingtheconventionfolder.subfolder:service.
Typewriter font
Identifiescharactersandvaluesthatyoumusttypeexactlyormessagesthatthesystemdisplaysontheconsole.
UPPERCASE Identifieskeyboardkeys.Keysthatyoumustpresssimultaneouslyarejoinedwiththe+symbol.
\ Directorypathsusethe\directorydelimiterunlessthesubjectisUNIXspecific.
[] Optionalkeywordsorvaluesareenclosedin[].Donottypethe[]symbolsinyourowncode.webMethods Developer Users Guide Version 7.1.1 15
About This Guide
Additional InformationThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyouwithimportantsourcesofinformationaboutwebMethodsproducts:
Troubleshooting Information.ThewebMethodsKnowledgeBaseprovidestroubleshootinginformationformanywebMethodsproducts.
Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,gototheDocumentationFeedbackFormonthewebMethodsBookshelf.
Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthedocumentationduringproductinstallationtoasingledirectorycalled_documentation,locatedbydefaultunderthewebMethodsinstallationdirectory.Inaddition,youcanfinddocumentationforallwebMethodsproductsonthewebMethodsBookshelf.16 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38webMethods Developer Users Guide Version 7.1.1 17
1 Getting Started with Developer
What Is Developer?webMethodsDeveloperisagraphicaldevelopmenttoolthatyouusetobuild,edit,andtestintegrationlogic.Itprovidesanintegrateddevelopmentenvironmentinwhichyoucandevelopthelogicandsupportingobjects(referredtoaselements)ofanintegrationsolution.Italsoprovidestoolsfortestinganddebuggingthesolutionsyoucreate.
DeveloperletsyourapidlyconstructintegrationlogicwithaneasytouseimplementationlanguagecalledthewebMethodsflowlanguage.Flowlanguageprovidesasetofsimplebutpowerfulconstructsthatyouusetospecifyasequenceofactions(steps)thattheIntegrationServerwillexecuteatruntime.Developeralsohasextensivedatatransformationandmappingcapabilitiesthatallowyoutoquicklydraganddropdatafieldsfromonesteptothenext.
Besidesprovidingtoolsforconstructingflowservices,Developerprovidesadditionaleditorsandtoolsforcreatingvariouselementsthatsupporttheexecutionofanintegrationsolution.Forexample,youuseDevelopertocreatethedocumenttypesandschemasusedfordatavalidationandtodefineBroker/localtriggerthatlaunchtheexecutionofserviceswhencertaindocumentsarepublished.
Developerenablesyoutolockanelementyouareworkingwith.Whenyoulockanelement,theelementisreadonlytoallotherusersontheIntegrationServer.Anotherusercannotedittheelementuntilyouunlockit.Developercanalsobeconfiguredtointeractwithathirdpartversioncontrolsystem(VCS)repository;inthiscase,elementsarelockedandunlockedasyoucheckthemoutofandintotheVCSrepository.
AllreferencesinthisguidetolockingrefertolocallockingontheIntegrationServer.Forspecificinformationaboutlocalfilelocking,seeChapter 4,LockingandUnlockingElements.ForinformationonhowtoimplementfilelockingwiththeVersionControlSystemIntegrationfeatureforDeveloper,seethewebMethodsVersionControlSystemIntegrationDevelopersGuideinthewebMethods_directory\_documentationdirectory.
Before You Use DeveloperDeveloperbuildsandeditsservicesdirectlyonaserver.TouseDeveloperyoumust:
HaveaccesstoawebMethodsIntegrationServeronwhichyoucanbuildandtestservices.
HaveauseraccountonthatwebMethodsIntegrationServer. BelongtoagroupthatisamemberoftheDevelopersACL(accesscontrollist)on
thatwebMethodsIntegrationServer.
IfyoudonothaveaccesstoawebMethodsIntegrationServeroryoudonothaveanappropriateuseraccountoraccessrights,seeyourserveradministrator.18 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
Starting DeveloperUsethefollowingproceduretostartDeveloperonyourworkstation.BeforeyoustartDevelopermakesurethattheIntegrationServerwithwhichyouwanttouseDeveloperisrunning.YoucannotworkwithDeveloperiftheserverisnotrunning.
1 OntheStartmenu,clickPrograms,andthenclickwebMethods.
2 ClickwebMethods Developer.
3 IntheOpenSessiondialogbox,completethefollowing:
Important! YoucanonlyconnectwebMethodsDeveloperversion7.1toawebMethodsIntegrationServerversion7.1.
To start Developer
In this field... Specify...
Server type Theregisteredtypefortheserveronwhichyouwanttoopenasession.ThedefaulttypeisIntegrationServer.
Server ThenameandportassignmentofthewebMethodsIntegrationServerinServerName:PortNumformat.
Examplerubicon:5555
Note: ServerstowhichyouhavesuccessfullyloggedoninthepastarelistedintheServerlist.Youcanselectaserverfromthislistortypeitsnameandportnumber.
Username Thenameofavaliduseraccountonthisserver.(TheusernamemustbeamemberofagroupbelongingtotheDevelopersACL.)
Usetheexactcombinationofupperandlowercasecharacterswithwhichitwasoriginallydefined.ISusernamesarecasesensitive.
Specify the name andport assignment of a
server...
...and enter a useraccount that has
developer privileges.webMethods Developer Users Guide Version 7.1.1 19
1 Getting Started with Developer
4 ClickOK.
Note: TheserverisinstalledwithadefaultuseraccountcalledDeveloperthathasdeveloperprivileges.
Password ThepasswordfortheuseraccountinUsername.Usetheexactcombinationofupperandlowercasecharacterswithwhichitwasoriginallydefined.ISpasswordsarecasesensitive.
Note: ThedefaultpasswordfortheDeveloperuseraccountisisdev.
Uses secure connection
WhetherthesessionwillbeopenedthroughHTTPorHTTPS.IfyouwanttoopenanHTTPSsessionontheselectedserverusingtheSecureSocketLayer(SSL),selectthischeckbox.IfyouwanttoopenanHTTPsessionontheserver,clearthischeckbox.
Uses proxy Whetherthesessionwillbeopenedthroughthedefaultproxyserver.Ifyouwanttoopenasessionontheselectedserverusingyourproxyserver,selectthischeckbox.
Tip! WhenyourunDeveloperfromthecommandline,Developerwritesmessagestotheconsole.TheamountandtypeofinformationthatiswrittenisdeterminedbythedebuglevelunderwhichDeveloperisoperating.Thedefaultdebuglevelis4.Ifyouwantmoredetailwrittentotheconsole,setthedebuglevelto10.Youcanchangethedebuglevelbyeditingtheini.cnffilelocatedinDeveloper_directory\config.
Note: WhenyoustartDeveloper,itverifiesthattheotherwebMethodscomponentssupportthesamelocaleasDeveloper.IfthelocaleofanaddincomponentisnotsupportedbytheDeveloperlocale,Developerdisplaysamessageintheconsolewarningyouofthelocalemismatch.Forexample,ifyoustartDeveloperinanEnglishlocalewithalocalizedJapaneseaddincomponent,Developerdisplaysthefollowingmessageintheconsole:
Warning: The following plug-ins are running localized versions even though Developer is not: ComponentName; VersionNumber.
DeveloperwilldisplaysometextinEnglishandthecomponentstextinJapanese.
In this field... Specify...20 webMethods Developer Users Guide Version 7.1.1
RoikkaHighlight
RoikkaHighlight
RoikkaHighlight
1 Getting Started with Developer
What Does the Developer Window Contain?TheDeveloperwindowisdividedintothefollowingareas:
Navigation panel.YouusetheNavigationpaneltoselect,lock,copy,move,delete,orrenameelements.IftheVCSIntegrationfeatureisenabled,youcancheckelementsintoandoutofaVCSrepository.Formoreinformationaboutthispanel,seeTheNavigationPanelonpage 22.
UDDI Registry tab.YouusetheUDDIRegistrytabtoconnecttoanddisconnectfromaUDDIRegistry,andtodisplay,filter,andpublishWebservices.Formoreinformationaboutthispanel,seeTheUDDIRegistryTabonpage 25.
Recent Elements tab.YouusetheRecentElementstabtoquicklyaccesselementsyouhaverecentlyviewed.Formoreinformationaboutthispanel,seeTheRecentElementsTabonpage 27.
Editor.YouusetheeditortoexamineandeditanelementyouopenedfromtheNavigationpanelorRecentElementstab.Formoreinformationabouttheeditor,seeTheEditoronpage 27.
Properties panel.YouusethePropertiespaneltoviewandeditthepropertiesforanitem.Formoreinformationaboutthispanel,seeThePropertiesPanelonpage 29.
Results panel.YouusetheResultspaneltoviewtheresultofaservicesexecution,toviewthevariablesthataserviceaddstothepipeline,andtoviewthecontentsofthosevariables.Formoreinformationaboutthispanel,seeTheResultsPanelonpage 31.
Developer main window The Navigation Panel
displays the contentsof servers, packages,
and folders.
The Editor displaysthe controls you use to
examine and edit anelement you have
opened from theNavigation panel or
Recent Elements tab.
The UDDI Registry tabdisplays Web services,if you are connected to
a UDDI Registry. TheRecent Elements Tabdisplays the elements
you viewed mostrecently.
The Properties Panel displays the properties for an item.
The Results Panel displays the results of a services execution.webMethods Developer Users Guide Version 7.1.1 21
1 Getting Started with Developer
The Navigation PanelTheNavigationpaneldisplaysthecontentsofpackagesonthewebMethodsIntegrationServersonwhichyouhaveanopensession.YouusetheNavigationpaneltoperformtaskssuchascreating,opening,locking,copying,moving,renaming,anddeletingelements.IftheVCSIntegrationfeatureisenabled,youcancheckelementsintoandoutofaVCSrepository.
ElementsintheNavigationpanelareshowninahierarchicalstructurewheretheserveristhetopmostelementinthehierarchy.Packagesontheservercontainoneormorefolders,whichcontainotherelementsthatyoucancreateandeditusingDeveloper(forexample,services,specifications,andISdocumenttypes).
FormoreinformationaboutthetasksyoucanperformonelementsintheNavigationpanel,seeChapter 2,ManagingElementsintheNavigationPanelandChapter 3,WorkingwithPackages.
ForinformationonhowtoimplementfilelockingwiththeVersionControlSystemIntegrationfeatureforDeveloper,seethewebMethodsVersionControlSystemIntegrationDevelopersGuideinthewebMethods_directory\_documentationdirectory.
Navigation Panel IconsEachitemintheNavigationpanelcontainsaniconthatdenotestheitemstype.Thefollowingtabledescribeswhateachiconrepresents.
This icon... Represents...
A server. YoucanhavemultipleservercontextsdisplayedinDeveloper.TheactiveservercontextistheonethatishighlightedintheNavigationpanel.Todisplaythecontentsoftheserver,clickthe symbolnexttoitsname.
A package.Apackagecontainsasetofservicesandrelatedfiles,suchasspecifications,ISdocumenttypes,andoutputtemplates.Todisplaythecontentsofapackage,click nexttoitsname.
A folder. Afoldercontainsrelatedservicesandoptionalfolders(calledsubfolders).Todisplaythecontentsofafolder,click nexttoitsname.
A flow service.AflowserviceisaservicewritteninthewebMethodsflowlanguage.
A Web service descriptor (WSD).AWebservicedescriptorisanISnamespaceelementthatcontainsthedefinitionofanISWebservice.AWSDdescribeseitheraprovideroraconsumerWebservice.FormoreinformationaboutusingWebservicesandtheUDDIRegistry,seetheWebServicesDevelopersGuide.22 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
A provider Web service descriptor (WSD).AWebservicedescriptorthatcontainsthedefinitionofaproviderISWebservice.AproviderWebserviceallowsanexternalusertoinvokeanexistingISserviceasanoperationoftheWebservice.
A consumer Web service descriptor (WSD).AWebservicedescriptorthatcontainsthedefinitionofaconsumerWebservice.ConsumerWebservicesareexternalWebservicesthatcanbeinvokedfromwithinthelocalIntegrationServer.
A Web service connector.AWebserviceconnectorisaflowservicethatinvokesaWebservicelocatedonaremoteserver.DeveloperautomaticallygeneratesaWebserviceconnectorwhenitcreatesaWebservicedescriptorforaconsumerWebservice.DevelopercanalsocreateaWebserviceconnectorfromanexistingWSDL.
A Java service.AJavaserviceisaservicewritteninJava.
A C service. ACserviceisaservicewritteninC/C++.
A specification.Aspecificationisaformaldescriptionofaservicesinputsandoutputs.
A Broker/local trigger. ABroker/localtriggeristriggerthatsubscribestoandprocessesdocumentspublished/deliveredlocallyortotheBroker.
FormoreinformationaboutcreatingBroker/localtriggers,seethePublishSubscribeDevelopersGuide.
A JMS trigger.AJMStriggerisatriggerthatreceivesmessagesfromadestination(queueortopic)onaJMSproviderandthenprocessesthosemessages.
FormoreinformationaboutcreatingJMStriggers,seethewebMethodsIntegrationServerJMSClientDevelopersGuide.
An IS document type. AnISdocumenttypecontainsasetoffieldsusedtodefinethestructureandtypeofdatainadocument.
A publishable document type.ApublishabledocumenttypeisanISdocumenttypewithspecificpublishingproperties.Instancesofpublishabledocumenttypescanbepublishedandsubscribedto.PublishabledocumenttypescanbeusedanywhereanISdocumenttypeisneeded.
A publishable document type for an adapter notification.AnadapternotificationcanhaveanassociatedpublishabledocumenttypethattheadapterusestosendthenotificationdatatoanIntegrationServeroraBroker.
This icon... Represents...webMethods Developer Users Guide Version 7.1.1 23
1 Getting Started with Developer
An IS schema. AnISschemaistheblueprintormodeldocumentagainstwhichyouvalidateanXMLdocument.TheschemadefineswhatcanandcannotbecontainedintheXMLdocumentsitvalidates.
An adapter notification.Anadapternotificationenablesanadaptertoreceiveeventdatafromtheadaptersresource.Therearetwotypesofadapternotifications:
Pollingnotifications,whichpolltheresourceforeventsthatoccurontheresource.
Listenernotifications,whichworkwithlistenerstodetectandprocesseventsthatoccurontheadapterresource.
Forinformationaboutcreatinganadapternotification,refertothedocumentationprovidedwiththeadapter.
An adapter service.Anadapterserviceconnectstoanadaptersresourceandinitiatesanoperationontheresource.Adapterservicesarecreatedusingservicetemplatesincludedwiththeadapter.Forinformationaboutcreatingadapterservices,refertothedocumentationprovidedwiththeadapter.
A listener.Alistenerisanobjectthatconnectstoanadapterresourceandwaitsfortheresourcetodeliverdatawhenaneventoccursontheresource.Listenersworkwithlistenernotificationstodetectandprocesseventdataontheadapterresource.Forinformationaboutcreatingalistener,refertothedocumentationprovidedwiththeadapter.
A connection.Aconnectionisanobjectthatcontainsparametersthatadapternotificationsandlistenersusetoconnecttoaresource.Forinformationaboutcreatingaconnection,refertothedocumentationprovidedwiththeadapter.
A flat file dictionary.Aflatfiledictionarycontainsrecorddefinitions,fielddefinitions,andcompositedefinitionsthatcanbeusedinmultipleflatfileschemas.Formoreinformationaboutcreatingaflatfiledictionary,seetheFlatFileSchemaDevelopersGuide.
A flat file schema.Aflatfileschemaistheblueprintthatcontainstheinstructionsforparsingorcreatingtherecordsinaflatfile,aswellastheconstraintstowhichaninboundflatfiledocumentshouldconformtobeconsideredvalid.Usingflatfileschemas,youcantranslatedocumentsintoandfromflatfileformats.Formoreinformationaboutcreatingaflatfileschema,seetheFlatFileSchemaDevelopersGuide.
An XSLT service.AnXSLTserviceconvertsXMLdataintootherXMLformatsorintoHTML,usingrulesdefinedinanassociatedXSLTstylesheet.FormoreinformationaboutcreatingXSLTservices,seetheXSLTServicesDevelopersGuide.
This icon... Represents...24 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
Refreshing the Contents of the Navigation PanelTheNavigationpanelonyourscreenisnotdynamicallyupdatedwhenotheruserslock,unlock,add,delete,orrenameelementsonaserver.TorefreshtheNavigationpaneltoreflectanychangesmadetothecontentsoftheserversyouareworkingwith,usetheSessionRefresh command.
The UDDI Registry TabUsetheUDDIRegistrytabtoconnecttoanddisconnectfromaUDDIRegistry.OnceyouhaveopenedaUDDIRegistry,youcandisplay,filter,andpublishWebservicesinthatregistry.WithintheUDDIRegistrytab,Webservicesaresortedinalphabeticalorder.SimplyselectaWebservicetoviewmoreinformationabouttheservice.FormoreinformationaboutusingWebservicesandtheUDDIRegistry,seetheWebServicesDevelopersGuide.
A .NET service. A.NETserviceisaservicethatcallsmethodsimportedfrom.NETassemblies(usingthewebMethodsforMicrosoftPlugin).Oncea.NETserviceexistswithinDeveloper,itcanbecomepartofaflowjustlikeanyotherservice.FormoreinformationaboutusingtheMicrosoft.NETapplicationplatformwithwebMethodscomponents,seethewebMethodsforMicrosoftPackageInstallationandUsersGuide.
An Unknown Node.ThewebMethodscomponentusedtocreate/developtheelementisnotinstalledontheclientmachine.
An Unknown Service.ThewebMethodscomponentusedtocreatethisserviceisnotinstalledontheclientmachine.
Note: OtherinstalledwebMethodscomponentsmightaddelementstotheNavigationpanelthatarenotdescribedintheprecedingtable.Forinformationabouttheseelements,refertothedocumentationprovidedwiththeseinstalledcomponents.
Note: Refreshingthesessionisdifferentfromrestoringasession.RestoringasessionallowsyoutosavechangestoanelementyouwereworkingwithwhentheIntegrationServershutsdownunexpectedly.Formoreinformationaboutrestoringsessions,seeRestoringaSessiononaServeronpage 36.
Note: WhenyouselectaWebserviceintheUDDIRegistrytab,theeditor(themiddleareaoftheDeveloperwindowbetweentheNavigationpanelandthePropertiespanel)isblank.ThisisbecauseDevelopercannotmodifyaWebservicepublishedtoaUDDIRegistry.
This icon... Represents...webMethods Developer Users Guide Version 7.1.1 25
1 Getting Started with Developer
UDDI Registry Tab IconsThefollowingbuttonsontheUDDIRegistrytabtoolbarareshortcutstofrequentlyusedcommands.
TheUDDIRegistrytabalsocontainsiconstorepresenttheUDDIRegistry,theregisteredbusinessentities,andtheWebservicesthathavebeenpublishedtotheUDDIRegistry.Thefollowingtableidentifiestheseicons.
Use this button... To...
ConnecttoaUDDIRegistrywhileworkinginDeveloper.
DisconnectfromaUDDIRegistrywhileworkinginDeveloper.
RefreshthedisplayofWebservices.EquivalenttoSessionRefresh UDDI Registry Display.CreateanexpressionthatfiltersthecontentsoftheUDDIRegistrytabbasedonthevalueofaWebserviceproperty.
RemovethefilterfromthecontentsoftheUDDIRegistrytabanddisplayallthepublishedWebservices.
CreateaWebservicedescriptor(WSD)fromtheWebserviceselectedintheUDDIRegistrytab.
This icon... Represents...
A UDDI Registry Node.DeveloperdisplaystheURLoftheUDDIRegistrytowhichyouareconnectednexttotheregistryicon.BelowtheUDDIRegistryname,DeveloperdisplaysallofthebusinessentitiesregisteredinthatUDDIRegistry.
A Business Entity.AbusinessentityisapublisherofWebservicestotheUDDIRegistry.Belowthebusinessentityname,DeveloperdisplaystheWebservicespublishedbythatentity.
A Web service.AWebserviceisasoftwareapplicationthatcanbeaccessedremotely,usingXMLbasedlanguagestocommunicate.FromaWebserviceoraWSDL,youcancreateaconsumerWebservicedescriptorandconnector.DevelopercaninvoketheconnectortoruntheremoteWebservice.FromanexistingISserviceorWSDL,youcancreateaproviderWebservicedescriptor.YoucanthenpublishtheWebservicedescriptortoaUDDIRegistrysothattheISserviceitdescribescanbeinvokedbyanexternaluserasanoperationoftheWebservice.FormoreinformationaboutusingWebservicesandtheUDDIRegistry,seetheWebServicesDevelopersGuide.26 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
The Recent Elements Tab TheRecentElementstabliststhelast30elementsyouviewedintheeditor.Developeraddsanelementtothispanelwhenyouclosetheelement.Youcanusethispaneltoquicklyopenelementsthatyouhaverecentlyviewedandclosed.
YoucanclearthelistofelementscurrentlydisplayedintheRecentElementstabbyclickingClear.
DeveloperhandleschangestotheRecentElementslistasfollows:
Whenyoucloseanopenelementintheeditor,DeveloperaddstheelementtothetopoftheRecentElementslist.
DeveloperremembersthecontentsoftheRecentElementstabbetweensessions.Ifyouattempttoopenanelementthatwasdeletedafteryouclos*edyourpreviousDevelopersession,Developeralertsyouthattheelementcannotbefoundandthenremovestheelementfromthelist.
IfyouattempttoopenanelementlistedintheRecentElementstabthatanotheruserhasdeleted,moved,orrenamedduringyourDevelopersession,Developerdisplaysamessagealertingyouthattheelementcannotbefound.
Ifyoumoveorrenameanelementduringyourcurrentsession,DeveloperautomaticallyrefreshestheRecentElementstabtoreflectthechange.Ifyoudeleteanelement,DeveloperremovestheelementfromtheRecentElementslist.
FormoreinformationaboutselectingelementsintheRecentElementstabtovieworeditintheeditor,seeOpeningandClosingElementsintheEditoronpage 45.
The EditorTheeditorcontainsthecontrolsthatyouusetoexamineandeditanelementyouopenfromtheNavigationpanelorRecentElementstab.Thecontentsoftheeditorvarydependingonthetypeofelementyouselect.
Forsomeelementtypes,theeditorisdividedintomultipleareas,includingtabscontainingadditionaleditingcontrolsfortheelement.YouswitchamongareaswithintheeditorjustasyouwouldbetweentheNavigationpanelorRecentElementstabandtheeditor.Toselectadifferentarea,clickanywhitespaceinthatarea.Todisplaythecontentsofatab,clickthetabname.
Tip! Toviewatooltipcontainingthefullyqualifiednameoftheelement,thepackageinwhichtheelementresides,andthehostnameandportnumberoftheserver,restthemousepointerontheelementname.webMethods Developer Users Guide Version 7.1.1 27
1 Getting Started with Developer
Editing controls for an element
Asmentionedearlier,youcanusetheNavigationpanelandRecentElementstabtoselectoneormoreelementstovieworeditintheeditor.Itishelpfultodisplaymultipleelementsintheeditorwhenyouareeditinganelementandyouwouldliketoreferbacktoanotherelementforinformation.Forexample,ifyouarecreatingoreditingaBroker/localtrigger,youmaywanttoquicklyviewthedocumenttypesandservicesassociatedwiththattrigger.
Eachelementyouopenhasitsowntabintheeditor.Theelementstitlebarcontainsthefullyqualifiednameoftheelementandiconstoindicatetheelementstypeandlockstatus.Formoreinformationabouttheseicons,seeNavigationPanelIconsonpage 22andWhatIsaLock?onpage 88.
Tip! YoucanpressCTRL+ALT+RIGHTARROWtotoggleforwardbetweenopenelementsintheeditorandCTRL+ALT+LEFTARROWtotogglebackward.
If you openan element
from theNavigation
panel...
...editingcontrols for that
element aredisplayed in the
editor.
In this example, a specification is opened in the editor.
The editor lists the input and output fields that were created for this specification. These lists are also referred to as trees.28 webMethods Developer Users Guide Version 7.1.1
1 Getting Started with Developer
Editor with multiple elements opened
The Properties Panel ThePropertiespaneldisplaysthepropertiesforthecurrentlyselecteditemintheDeveloperwindow.Youusethispaneltoviewandeditthepropertiesofanitem(suchasanelement,astepinaflowservice,afieldinadocument,oralinkbetweentwovariables).
ThepropertiesthatDeveloperdisplaysinthispanelvarydependingontheitemyouselectandwhichareaoftheDeveloperwindowhasthefocus.DeveloperidentifiestheitemforwhichpropertiesaredisplayedbeneaththetitlebarofthePropertiespanel.
Tip! YoucanlocatetheactiveelementintheNavigationpanelbyusingtheEditLocate in Navigationcommand.
Tip! IfthePropertiespaneldisplaysthepropertiesforanitem(forexample,adocumentfield)andyouwanttodisplaythepropertiesforitsparentelement(forexample,thedocumenttypetowhichthefieldbelongs),clickthetitlebaroftheparentelementintheeditor,thetaboftheparentelementintheeditor,orthewhitespacewithintheeditor.
Each opened elementin the editor has its
own tab.Click to view tabs that are not currently visible.
Click to close the active element (that is, the element that is currently displayed).
The elements title bardisplays the elements
fully qualified name.
Some elements havespecialized tabs.webMethods Developer Users Guide Version 7.1.1 29
1 Getting Started with Developer
Properties panel
Dependingonthetypeofpropertyyouselect,youeditapropertyby:
Typingavalueintheboxtotherightofthepropertyname(forexample,tospecifythenamespaceandlocalnamesthatmakeuptheuniversalnameforaservice)
Selectingavaluefromalist(forexample,tospecifyavalid