TitlePage

webMethods Developer
Users Guide

Version 7.1.1

January 2008

webMethods

Copyright & Docu mentID

ThisdocumentappliestowebMethodsDeveloperVersion 7.1.1andwebMethodsIntegrationServerVersion 7.1.1andtoallsubsequent releases. Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions. CopyrightSoftwareAG2008. Allrightsreserved. ThenameSoftwareAGand/orallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.Other companyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners. Document ID: DEV-UG-711-20080128

Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Getting Started with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigation Panel Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refreshing the Contents of the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . The UDDI Registry Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDDI Registry Tab Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Recent Elements Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Properties Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving Between Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resizing Areas in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hiding and Showing Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dragging Movable Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Switching Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restoring a Session on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notification of Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Managing Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Names and Element Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Naming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 16 17 18 18 19 21 22 22 25 25 26 27 27 29 31 31 31 32 33 33 33 34 35 36 36 37 37 38 39 40 41 41 42 42 43 43 44

webMethods Developer Users Guide Version 7.1.1

Table of Contents

Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving and Copying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Elements Between Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving and Copying Adapter Notifications and Related Elements . . . . . . . . . . . . . . . . Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Elements in the Navigation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Fields in Editor Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locating Invoked Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing the Developer Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Working with Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Naming Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Details for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Optimizing Lock Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying a Package to Another Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documenting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reloading a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting a Package or Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning a Version Number to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Patch History for a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Startup Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Shutdown Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Replication Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . Removing Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . .

45 47 47 47 48 49 51 53 53 55 55 58 59 60 60 61 63 66 66 69 70 70 72 72 73 73 74 76 77 77 78 78 79 81 83 83 83 84 84 85 85 86

webMethods Developer Users Guide Version 7.1.1

Table of Contents

4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Do I Know Who Has an Element Locked? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Do I Lock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Do I Unlock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unlocking Elements Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unlocking an Element Using the Integration Server Administrator . . . . . . . . . . . . . . . . Unlocking a System Locked Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing an Elements Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . . Automatically Unlocking Elements After Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lock/Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. Assigning and Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When a Client Runs a Service with ACLs? . . . . . . . . . . . . . . . . . . . . . Am I Required to Use ACLs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Do I Create an ACL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Permissions Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default ACLs and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Testing/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

87 88 88 89 89 89 90 90 91 92 92 92 94 94 94 95 97 98 98 99 99 100 100 101 101 103 104 104 104 106 106 106 107 109 109 109 111 111 111 112 112

webMethods Developer Users Guide Version 7.1.1

Table of Contents

6. Building Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flow Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is the Pipeline? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Are Input and Output Parameters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package and Folder Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Default Logic Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Completing the Input/Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining the State of a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring a Services Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of Services to Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services Suited for Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services that You Should Not Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling a Services Use of Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Duration of a Cached Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Prefetch Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Execution Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Universal Names to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Auditing for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying When Audit Data Is Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including the Pipeline in the Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Is a Copy of the Input Pipeline Saved in the Audit Log? . . . . . . . . . . . . . . . Service Auditing Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Auditing for Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Auditing Long-Running Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Auditing Options for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audit Level Settings in Earlier Versions of Developer . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

115 116 116 117 118 119 120 120 120 121 121 122 123 123 124 125 127 129 130 131 131 131 131 132 132 133 134 135 136 136 137 140 141 142 143 144 146 146 146 147 147 148 149 149

webMethods Developer Users Guide Version 7.1.1

Table of Contents

7. Inserting Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Position of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Level of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Properties of a Flow Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Service Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking a Built-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking a Service on Another webMethods Integration Server . . . . . . . . . . . . . . . . . . Building an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Switch Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Label Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching on an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching on Null and Empty Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Default Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using SEQUENCE as the Target of a BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the REPEAT Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the REPEAT Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using REPEAT to Retry a Failed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using REPEAT to Retry a Successful Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using SEQUENCE to Specify an Exit Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Input Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collecting Output from a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Mapping Data in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Data Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does the Pipeline Tab Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pipeline Tab for an INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pipeline Tab for a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pipeline Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Mapping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Linking Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When Integration Server Executes a Link Between Variables? . .

151 152 152 154 154 156 157 157 158 158 158 160 160 161 161 163 164 165 166 168 170 170 171 171 171 174 176 176 178 179 179 180 181 183 185 186 186 187 189 190 190 191 192 196

webMethods Developer Users Guide Version 7.1.1

Table of Contents

Linking to Document and Document List Variables . . . . . . . . . . . . . . . . . . . . . . . . Linking Variables of Different Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples of Structural Transformations on the Pipeline Tab . . . . . . . . . . . . Converting a String List to a Document List . . . . . . . . . . . . . . . . . . . . . . . . . . Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . Deleting Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Conditions to Links Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . Linking Multiple Source Variables to a Target Variable . . . . . . . . . . . . . . . . . Assigning Values to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning a Default Value to a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initializing Variables in a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Other Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Value for a Pipeline Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Set Values Between Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dropping Variables from the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Variables with the Pipeline Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Are Transformers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Built-in Services as Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting a Transformer into a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Linking Variables to a Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transformer Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transformers and Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Dimensionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validating Input and Output for Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Expanding Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renaming Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . . . . . . . . Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does an IS Schema Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schema Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schema Details Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating IS Schemas from XML Schemas that Reference Other Schemas . . . . . Editing a Simple Type in an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Constraining Facet Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . .

198 199 200 200 201 203 204 204 205 206 207 207 208 208 209 210 211 212 212 214 214 215 217 217 217 218 218 218 219 220 221 222 223 224 224 225 228 229 230 231 233 233 234 235

webMethods Developer Users Guide Version 7.1.1

Table of Contents

Points to Consider for All Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Points to Consider When Using a DTD As the Source . . . . . . . . . . . . . . . . . . . . . 236 Points to Consider When Using an XML Schema As the Source . . . . . . . . . . . . . 236 Expanding Complex Document Types Inline . . . . . . . . . . . . . . . . . . . . . . . . . 237 Generating Fields for Substitution Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Creating an IS Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . 240 The Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . 243 Editing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Printing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Using an IS Document Type to Specify Service Input or Output Parameters . . . . . . . 245 Using an IS Document Type to Build a Document Reference or Document Reference List Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Specifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 10. Performing Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Data Validated Against? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing a String Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Constraints Applied to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Input/Output Validation via the Input/Output Tab . . . . . . . . . . . . . . . . . . . . Specifying Input/Output Validation via the INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Out of Memory During Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Testing and Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Entering Input for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving Input Values to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading Input Values from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Results of the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Variables from the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run-Time Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 254 254 255 257 257 259 259 261 262 263 263 264 265 266 266 267 269 270 270 271 272 274 274 275 277 277

webMethods Developer Users Guide Version 7.1.1

Table of Contents

The Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Pipeline Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Entering Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Combining the Step and Trace Commands in Debug Mode . . . . . . . . . . . . . . . . . . . . Resetting Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Trace Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tracing into a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Step Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stepping though a Child Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Step Tools with a MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When a Breakpoint Is Encountered? . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Breakpoints on Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing a List of Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling a Condition Placed on a Link Between Variables . . . . . . . . . . . . . . . . . . . . . Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving the Contents of the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading a Saved Pipeline into the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Servers Debug Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Contents of the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Debug Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Information to the Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing an Arbitrary Message to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dumping the Pipeline to the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Building Coded Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The IData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services Take IData Objects as Input and Return IData as Output . . . . . . . . . . . Getting and Setting Elements in an IData Object . . . . . . . . . . . . . . . . . . . . . . . . . Creating IData Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

278 279 279 280 281 282 283 283 284 285 286 287 288 288 289 290 291 291 291 293 294 295 296 296 297 298 298 299 299 300 300 301 301 302 302 304 307 308 308 308 309 309 310 310

10

webMethods Developer Users Guide Version 7.1.1

Table of Contents

Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Developer IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Java Service Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Shared Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Java Service with Developers IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Java Code from Service Input and Output Parameters . . . . . . . . . . . Setting Run-Time Options for a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Namespace Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Source Code Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing the Source Code for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the webMethods API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Basic Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commenting Code for the webMethods Integration Server . . . . . . . . . . . . . . . . . Using the jcode Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Make Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fragment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Composite Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other jcode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Files for a C/C++ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Java Code for a C Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building the C/C++ Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13. Creating Client Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

311 311 311 313 314 315 317 317 317 318 319 319 319 320 321 321 321 322 322 323 324 324 326 327 328 328 328 329 331 332 332 332 333 334 334 335 335 335 336 336 337 337 337 337

webMethods Developer Users Guide Version 7.1.1

11

Table of Contents

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files for the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files Containing the Code that Invokes the Service . . . . . . . . . . . . . . . . . . . . . . . File Containing the Code that Interacts with webMethods Integration Server . . . . Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Services with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the HTTP GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the HTTP POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input to the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output from the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14. Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Are Event Handlers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When an Event Occurs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribing to an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Event Filters for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing and Editing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting an Event Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guaranteed Delivery Events and Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Guaranteed Delivery Start Events . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Guaranteed Delivery End Events . . . . . . . . . . . . . . . . . . . . . . . . Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

337 338 338 338 339 339 339 339 340 340 341 341 341 341 342 342 343 343 345 347 348 350 350 350 351 352 355 355 356 356 357 357 359 360 360 361 362 363 364 364 365 366 366 367

12

webMethods Developer Users Guide Version 7.1.1

Table of Contents

Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Session Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Session End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Session Expire Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Transaction Start Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Handlers for Transaction End Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. Building Services that Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Services and Retry Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Build a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . ExampleBuilding a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . A. webMethods Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching on a Switch Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching on Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions that Will Cause a BRANCH Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions that Will Cause an INVOKE Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions that Will Cause a LOOP Step to Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Does REPEAT Fail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples of When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions that Will Cause the SEQUENCE Step to Fail . . . . . . . . . . . . . . . . . . . . . . .

367 368 368 369 369 370 370 370 372 372 373 375 376 376 376 377 377 380 383 384 384 384 385 386 386 387 387 388 388 388 389 389 390 390 391 391 391 392 393 393 394 394 395

webMethods Developer Users Guide Version 7.1.1

13

Table of Contents

B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java Classes for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How webMethods Developer Supports Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparing Java Objects to Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking for Variable Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lexical Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Variables that Contain Special Characters . . . . . . . . . . . . . . . . . . . . . . . . Typing Special Characters in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample CodeIData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F. Validation Content Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G. Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

397 398 398 398 405 406 407 409 409 413 414 415 417 418 418 418 419 421 423 424 425 426 427 428 431 432 432 432 437 438 438 448 451 452 452 465 470

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

14

webMethods Developer Users Guide Version 7.1.1

About This Guide

ThisguidedescribeshowtocreateservicesusingwebMethodsDeveloper.Itcontains informationfordeveloperswhowanttobuildservicesusingthewebMethodsflow languageoraprogramminglanguagesuchasJava,C/C++,orVisualBasic. Tousethisguideeffectively,youshouldknowhowtoprograminJava,C/C++,and/or VisualBasicifyouwillbecreatingservicesinthoselanguages.

Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchangebased onyourspecificsituationorenvironment.Identifiestermsthefirst timetheyaredefinedintext.Alsoidentifiesserviceinputandoutput variables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously arejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.

Narrow font
Typewriter font

UPPERCASE \ [ ]

webMethods Developer Users Guide Version 7.1.1

15

About This Guide

Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovides youwithimportantsourcesofinformationaboutwebMethodsproducts: Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides troubleshootinginformationformanywebMethodsproducts. Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto theDocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe documentationduringproductinstallationtoasingledirectorycalled _documentation,locatedbydefaultunderthewebMethodsinstallationdirectory. Inaddition,youcanfinddocumentationforallwebMethodsproductsonthe webMethodsBookshelf.

16

webMethods Developer Users Guide Version 7.1.1

Getting Started with Developer

18 18 19 21 31 35 37 38

What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

17

1 Getting Started with Developer

What Is Developer?
webMethodsDeveloperisagraphicaldevelopmenttoolthatyouusetobuild,edit,and testintegrationlogic.Itprovidesanintegrateddevelopmentenvironmentinwhichyou candevelopthelogicandsupportingobjects(referredtoaselements)ofanintegration solution.Italsoprovidestoolsfortestinganddebuggingthesolutionsyoucreate. Developerletsyourapidlyconstructintegrationlogicwithaneasytouse implementationlanguagecalledthewebMethodsflowlanguage.Flowlanguageprovidesa setofsimplebutpowerfulconstructsthatyouusetospecifyasequenceofactions(steps) thattheIntegrationServerwillexecuteatruntime.Developeralsohasextensivedata transformationandmappingcapabilitiesthatallowyoutoquicklydraganddropdata fieldsfromonesteptothenext. Besidesprovidingtoolsforconstructingflowservices,Developerprovidesadditional editorsandtoolsforcreatingvariouselementsthatsupporttheexecutionofan integrationsolution.Forexample,youuseDevelopertocreatethedocumenttypesand schemasusedfordatavalidationandtodefineBroker/localtriggerthatlaunchthe executionofserviceswhencertaindocumentsarepublished. Developerenablesyoutolockanelementyouareworkingwith.Whenyoulockan element,theelementisreadonlytoallotherusersontheIntegrationServer.Another usercannotedittheelementuntilyouunlockit.Developercanalsobeconfiguredto interactwithathirdpartversioncontrolsystem(VCS)repository;inthiscase,elements arelockedandunlockedasyoucheckthemoutofandintotheVCSrepository. AllreferencesinthisguidetolockingrefertolocallockingontheIntegrationServer.For specificinformationaboutlocalfilelocking,seeChapter 4,LockingandUnlocking Elements.ForinformationonhowtoimplementfilelockingwiththeVersionControl SystemIntegrationfeatureforDeveloper,seethewebMethodsVersionControlSystem IntegrationDevelopersGuideinthewebMethods_directory\_documentationdirectory.

Before You Use Developer

Developerbuildsandeditsservicesdirectlyonaserver.TouseDeveloperyoumust: HaveaccesstoawebMethodsIntegrationServeronwhichyoucanbuildandtest services. HaveauseraccountonthatwebMethodsIntegrationServer. BelongtoagroupthatisamemberoftheDevelopersACL(accesscontrollist)on thatwebMethodsIntegrationServer. IfyoudonothaveaccesstoawebMethodsIntegrationServeroryoudonothavean appropriateuseraccountoraccessrights,seeyourserveradministrator.

18

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

Starting Developer
UsethefollowingproceduretostartDeveloperonyourworkstation.Beforeyoustart DevelopermakesurethattheIntegrationServerwithwhichyouwanttouseDeveloperis running.YoucannotworkwithDeveloperiftheserverisnotrunning. Important! YoucanonlyconnectwebMethodsDeveloperversion7.1toawebMethods IntegrationServerversion7.1. To start Developer 1 2 OntheStartmenu,clickPrograms,andthenclickwebMethods. ClickwebMethods Developer.

Specify the name and port assignment of a server... ...and enter a user account that has developer privileges.

IntheOpenSessiondialogbox,completethefollowing: In this field... Server type Server Specify... Theregisteredtypefortheserveronwhichyouwanttoopena session.ThedefaulttypeisIntegrationServer. ThenameandportassignmentofthewebMethodsIntegration ServerinServerName:PortNumformat. Examplerubicon:5555 Note: Serverstowhichyouhavesuccessfullyloggedoninthe pastarelistedintheServerlist.Youcanselectaserverfromthis listortypeitsnameandportnumber. Username Thenameofavaliduseraccountonthisserver.(Theusername mustbeamemberofagroupbelongingtotheDevelopersACL.) Usetheexactcombinationofupperandlowercasecharacters withwhichitwasoriginallydefined.ISusernamesarecase sensitive.

webMethods Developer Users Guide Version 7.1.1

19

1 Getting Started with Developer

In this field...

Specify... Note: Theserverisinstalledwithadefaultuseraccountcalled Developerthathasdeveloperprivileges.

Password

ThepasswordfortheuseraccountinUsername.Usetheexact combinationofupperandlowercasecharacterswithwhichit wasoriginallydefined.ISpasswordsarecasesensitive. Note: ThedefaultpasswordfortheDeveloperuseraccountis isdev.

Uses secure connection

WhetherthesessionwillbeopenedthroughHTTPorHTTPS.If youwanttoopenanHTTPSsessionontheselectedserverusing theSecureSocketLayer(SSL),selectthischeckbox.Ifyouwant toopenanHTTPsessionontheserver,clearthischeckbox. Whetherthesessionwillbeopenedthroughthedefaultproxy server.Ifyouwanttoopenasessionontheselectedserverusing yourproxyserver,selectthischeckbox.

Uses proxy

ClickOK. Tip! WhenyourunDeveloperfromthecommandline,Developerwritesmessagesto theconsole.Theamountandtypeofinformationthatiswrittenisdeterminedbythe debuglevelunderwhichDeveloperisoperating.Thedefaultdebuglevelis4.Ifyou wantmoredetailwrittentotheconsole,setthedebuglevelto10.Youcanchangethe debuglevelbyeditingtheini.cnffilelocatedinDeveloper_directory\config. Note: WhenyoustartDeveloper,itverifiesthattheotherwebMethodscomponents supportthesamelocaleasDeveloper.Ifthelocaleofanaddincomponentisnot supportedbytheDeveloperlocale,Developerdisplaysamessageintheconsole warningyouofthelocalemismatch.Forexample,ifyoustartDeveloperinanEnglish localewithalocalizedJapaneseaddincomponent,Developerdisplaysthefollowing messageintheconsole:
Warning: The following plug-ins are running localized versions even though Developer is not: ComponentName; VersionNumber.

DeveloperwilldisplaysometextinEnglishandthecomponentstextinJapanese.

20

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

What Does the Developer Window Contain?

TheDeveloperwindowisdividedintothefollowingareas: Navigation panel.YouusetheNavigationpaneltoselect,lock,copy,move,delete,or renameelements.IftheVCSIntegrationfeatureisenabled,youcancheckelementsin toandoutofaVCSrepository.Formoreinformationaboutthispanel,seeThe NavigationPanelonpage 22. UDDI Registry tab.YouusetheUDDIRegistrytabtoconnecttoanddisconnectfroma UDDIRegistry,andtodisplay,filter,andpublishWebservices.Formoreinformation aboutthispanel,seeTheUDDIRegistryTabonpage 25. Recent Elements tab.YouusetheRecentElementstabtoquicklyaccesselementsyou haverecentlyviewed.Formoreinformationaboutthispanel,seeTheRecent ElementsTabonpage 27. Editor.Youusetheeditortoexamineandeditanelementyouopenedfromthe NavigationpanelorRecentElementstab.Formoreinformationabouttheeditor,see TheEditoronpage 27. Properties panel.YouusethePropertiespaneltoviewandeditthepropertiesforan item.Formoreinformationaboutthispanel,seeThePropertiesPanelonpage 29. Results panel.YouusetheResultspaneltoviewtheresultofaservicesexecution,to viewthevariablesthataserviceaddstothepipeline,andtoviewthecontentsof thosevariables.Formoreinformationaboutthispanel,seeTheResultsPanelon page 31. Developer main window
The Navigation Panel displays the contents of servers, packages, and folders. The Editor displays the controls you use to examine and edit an element you have opened from the Navigation panel or Recent Elements tab. The UDDI Registry tab displays Web services, if you are connected to a UDDI Registry. The Recent Elements Tab displays the elements you viewed most recently.

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 Panel

TheNavigationpaneldisplaysthecontentsofpackagesonthewebMethodsIntegration Serversonwhichyouhaveanopensession.YouusetheNavigationpaneltoperform taskssuchascreating,opening,locking,copying,moving,renaming,anddeleting elements.IftheVCSIntegrationfeatureisenabled,youcancheckelementsintoandout ofaVCSrepository. ElementsintheNavigationpanelareshowninahierarchicalstructurewheretheserver isthetopmostelementinthehierarchy.Packagesontheservercontainoneormore folders,whichcontainotherelementsthatyoucancreateandeditusingDeveloper(for example,services,specifications,andISdocumenttypes). FormoreinformationaboutthetasksyoucanperformonelementsintheNavigation panel,seeChapter 2,ManagingElementsintheNavigationPanelandChapter 3, WorkingwithPackages. ForinformationonhowtoimplementfilelockingwiththeVersionControlSystem IntegrationfeatureforDeveloper,seethewebMethodsVersionControlSystemIntegration DevelopersGuideinthewebMethods_directory\_documentationdirectory.

Navigation Panel Icons

EachitemintheNavigationpanelcontainsaniconthatdenotestheitemstype.The followingtabledescribeswhateachiconrepresents. This icon... Represents... A server. YoucanhavemultipleservercontextsdisplayedinDeveloper. TheactiveservercontextistheonethatishighlightedintheNavigation panel.Todisplaythecontentsoftheserver,clickthe symbolnexttoits name. A package.Apackagecontainsasetofservicesandrelatedfiles,suchas specifications,ISdocumenttypes,andoutputtemplates.Todisplaythe contentsofapackage,click nexttoitsname. A folder. Afoldercontainsrelatedservicesandoptionalfolders(called subfolders).Todisplaythecontentsofafolder,click nexttoitsname. A flow service.AflowserviceisaservicewritteninthewebMethodsflow language. A Web service descriptor (WSD).AWebservicedescriptorisanISnamespace elementthatcontainsthedefinitionofanISWebservice.AWSD describeseitheraprovideroraconsumerWebservice.Formore informationaboutusingWebservicesandtheUDDIRegistry,seetheWeb ServicesDevelopersGuide.

22

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

This icon...

Represents... A provider Web service descriptor (WSD).AWebservicedescriptorthat containsthedefinitionofaproviderISWebservice.AproviderWeb serviceallowsanexternalusertoinvokeanexistingISserviceasan operationoftheWebservice. A consumer Web service descriptor (WSD).AWebservicedescriptorthat containsthedefinitionofaconsumerWebservice.ConsumerWeb servicesareexternalWebservicesthatcanbeinvokedfromwithinthe localIntegrationServer. A Web service connector.AWebserviceconnectorisaflowservicethat invokesaWebservicelocatedonaremoteserver.Developer automaticallygeneratesaWebserviceconnectorwhenitcreatesaWeb servicedescriptorforaconsumerWebservice.Developercanalsocreatea WebserviceconnectorfromanexistingWSDL. A Java service.AJavaserviceisaservicewritteninJava. A C service. ACserviceisaservicewritteninC/C++. A specification.Aspecificationisaformaldescriptionofaservicesinputs andoutputs. A Broker/local trigger. ABroker/localtriggeristriggerthatsubscribestoand processesdocumentspublished/deliveredlocallyortotheBroker. FormoreinformationaboutcreatingBroker/localtriggers,seethePublish SubscribeDevelopersGuide. A JMS trigger.AJMStriggerisatriggerthatreceivesmessagesfroma destination(queueortopic)onaJMSproviderandthenprocessesthose messages. FormoreinformationaboutcreatingJMStriggers,seethewebMethods IntegrationServerJMSClientDevelopersGuide. An IS document type. AnISdocumenttypecontainsasetoffieldsusedto definethestructureandtypeofdatainadocument. A publishable document type.ApublishabledocumenttypeisanIS documenttypewithspecificpublishingproperties.Instancesof publishabledocumenttypescanbepublishedandsubscribedto. PublishabledocumenttypescanbeusedanywhereanISdocumenttype isneeded. A publishable document type for an adapter notification.Anadapternotification canhaveanassociatedpublishabledocumenttypethattheadapteruses tosendthenotificationdatatoanIntegrationServeroraBroker.

webMethods Developer Users Guide Version 7.1.1

23

1 Getting Started with Developer

This icon...

Represents... An IS schema. AnISschemaistheblueprintormodeldocumentagainst whichyouvalidateanXMLdocument.Theschemadefineswhatcanand cannotbecontainedintheXMLdocumentsitvalidates. An adapter notification.Anadapternotificationenablesanadapterto receiveeventdatafromtheadaptersresource.Therearetwotypesof adapternotifications: Pollingnotifications,whichpolltheresourceforeventsthatoccuron theresource. Listenernotifications,whichworkwithlistenerstodetectandprocess eventsthatoccurontheadapterresource. Forinformationaboutcreatinganadapternotification,refertothe documentationprovidedwiththeadapter. An adapter service.Anadapterserviceconnectstoanadaptersresource andinitiatesanoperationontheresource.Adapterservicesarecreated usingservicetemplatesincludedwiththeadapter.Forinformationabout creatingadapterservices,refertothedocumentationprovidedwiththe adapter. A listener.Alistenerisanobjectthatconnectstoanadapterresourceand waitsfortheresourcetodeliverdatawhenaneventoccursonthe resource.Listenersworkwithlistenernotificationstodetectandprocess eventdataontheadapterresource.Forinformationaboutcreatinga listener,refertothedocumentationprovidedwiththeadapter. A connection.Aconnectionisanobjectthatcontainsparametersthat adapternotificationsandlistenersusetoconnecttoaresource.For informationaboutcreatingaconnection,refertothedocumentation providedwiththeadapter. A flat file dictionary.Aflatfiledictionarycontainsrecorddefinitions,field definitions,andcompositedefinitionsthatcanbeusedinmultipleflatfile schemas.Formoreinformationaboutcreatingaflatfiledictionary,seethe FlatFileSchemaDevelopersGuide. A flat file schema.Aflatfileschemaistheblueprintthatcontainsthe instructionsforparsingorcreatingtherecordsinaflatfile,aswellasthe constraintstowhichaninboundflatfiledocumentshouldconformtobe consideredvalid.Usingflatfileschemas,youcantranslatedocuments intoandfromflatfileformats.Formoreinformationaboutcreatingaflat fileschema,seetheFlatFileSchemaDevelopersGuide. An XSLT service.AnXSLTserviceconvertsXMLdataintootherXML formatsorintoHTML,usingrulesdefinedinanassociatedXSLT stylesheet.FormoreinformationaboutcreatingXSLTservices,seethe XSLTServicesDevelopersGuide.

24

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

This icon...

Represents... A .NET service. A.NETserviceisaservicethatcallsmethodsimported from.NETassemblies(usingthewebMethodsforMicrosoftPlugin). Oncea.NETserviceexistswithinDeveloper,itcanbecomepartofaflow justlikeanyotherservice.Formoreinformationaboutusingthe Microsoft.NETapplicationplatformwithwebMethodscomponents,see thewebMethodsforMicrosoftPackageInstallationandUsersGuide. An Unknown Node.ThewebMethodscomponentusedtocreate/developthe elementisnotinstalledontheclientmachine. An Unknown Service.ThewebMethodscomponentusedtocreatethis serviceisnotinstalledontheclientmachine.

Note: OtherinstalledwebMethodscomponentsmightaddelementstotheNavigation panelthatarenotdescribedintheprecedingtable.Forinformationaboutthese elements,refertothedocumentationprovidedwiththeseinstalledcomponents.

Refreshing the Contents of the Navigation Panel

TheNavigationpanelonyourscreenisnotdynamicallyupdatedwhenotheruserslock, unlock,add,delete,orrenameelementsonaserver.TorefreshtheNavigationpanelto reflectanychangesmadetothecontentsoftheserversyouareworkingwith,usethe SessionRefresh command. Note: Refreshingthesessionisdifferentfromrestoringasession.Restoringasession allowsyoutosavechangestoanelementyouwereworkingwithwhenthe IntegrationServershutsdownunexpectedly.Formoreinformationaboutrestoring sessions,seeRestoringaSessiononaServeronpage 36.

The UDDI Registry Tab

UsetheUDDIRegistrytabtoconnecttoanddisconnectfromaUDDIRegistry.Onceyou haveopenedaUDDIRegistry,youcandisplay,filter,andpublishWebservicesinthat registry.WithintheUDDIRegistrytab,Webservicesaresortedinalphabeticalorder. SimplyselectaWebservicetoviewmoreinformationabouttheservice.Formore informationaboutusingWebservicesandtheUDDIRegistry,seetheWebServices DevelopersGuide. Note: WhenyouselectaWebserviceintheUDDIRegistrytab,theeditor(themiddle areaoftheDeveloperwindowbetweentheNavigationpanelandtheProperties panel)isblank.ThisisbecauseDevelopercannotmodifyaWebservicepublishedtoa UDDIRegistry.

webMethods Developer Users Guide Version 7.1.1

25

1 Getting Started with Developer

UDDI Registry Tab Icons

ThefollowingbuttonsontheUDDIRegistrytabtoolbarareshortcutstofrequentlyused commands. Use this button... To... ConnecttoaUDDIRegistrywhileworkinginDeveloper. DisconnectfromaUDDIRegistrywhileworkinginDeveloper. RefreshthedisplayofWebservices.EquivalenttoSessionRefresh UDDI Registry Display. CreateanexpressionthatfiltersthecontentsoftheUDDIRegistrytab basedonthevalueofaWebserviceproperty. RemovethefilterfromthecontentsoftheUDDIRegistrytaband displayallthepublishedWebservices. CreateaWebservicedescriptor(WSD)fromtheWebserviceselectedin theUDDIRegistrytab. TheUDDIRegistrytabalsocontainsiconstorepresenttheUDDIRegistry,theregistered businessentities,andtheWebservicesthathavebeenpublishedtotheUDDIRegistry. Thefollowingtableidentifiestheseicons. This icon... Represents... A UDDI Registry Node.DeveloperdisplaystheURLoftheUDDIRegistry towhichyouareconnectednexttotheregistryicon.BelowtheUDDI Registryname,Developerdisplaysallofthebusinessentitiesregistered inthatUDDIRegistry. A Business Entity.AbusinessentityisapublisherofWebservicestothe UDDIRegistry.Belowthebusinessentityname,Developerdisplaysthe Webservicespublishedbythatentity. A Web service.AWebserviceisasoftwareapplicationthatcanbe accessedremotely,usingXMLbasedlanguagestocommunicate.From aWebserviceoraWSDL,youcancreateaconsumerWebservice descriptorandconnector.Developercaninvoketheconnectortorun theremoteWebservice.FromanexistingISserviceorWSDL,youcan createaproviderWebservicedescriptor.YoucanthenpublishtheWeb servicedescriptortoaUDDIRegistrysothattheISserviceitdescribes canbeinvokedbyanexternaluserasanoperationoftheWebservice. FormoreinformationaboutusingWebservicesandtheUDDIRegistry, seetheWebServicesDevelopersGuide.

26

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

The Recent Elements Tab

TheRecentElementstabliststhelast30elementsyouviewedintheeditor.Developer addsanelementtothispanelwhenyouclosetheelement.Youcanusethispanelto quicklyopenelementsthatyouhaverecentlyviewedandclosed. Tip! Toviewatooltipcontainingthefullyqualifiednameoftheelement,thepackage inwhichtheelementresides,andthehostnameandportnumberoftheserver,rest themousepointerontheelementname. YoucanclearthelistofelementscurrentlydisplayedintheRecentElementstabby clickingClear. DeveloperhandleschangestotheRecentElementslistasfollows: Whenyoucloseanopenelementintheeditor,Developeraddstheelementtothetop oftheRecentElementslist. DeveloperremembersthecontentsoftheRecentElementstabbetweensessions.If youattempttoopenanelementthatwasdeletedafteryouclos*edyourprevious Developersession,Developeralertsyouthattheelementcannotbefoundandthen removestheelementfromthelist. IfyouattempttoopenanelementlistedintheRecentElementstabthatanotheruser hasdeleted,moved,orrenamedduringyourDevelopersession,Developerdisplaysa messagealertingyouthattheelementcannotbefound. Ifyoumoveorrenameanelementduringyourcurrentsession,Developer automaticallyrefreshestheRecentElementstabtoreflectthechange.Ifyoudeletean element,DeveloperremovestheelementfromtheRecentElementslist. FormoreinformationaboutselectingelementsintheRecentElementstabtovieworedit intheeditor,seeOpeningandClosingElementsintheEditoronpage 45.

The Editor
Theeditorcontainsthecontrolsthatyouusetoexamineandeditanelementyouopen fromtheNavigationpanelorRecentElementstab.Thecontentsoftheeditorvary dependingonthetypeofelementyouselect. Forsomeelementtypes,theeditorisdividedintomultipleareas,includingtabs containingadditionaleditingcontrolsfortheelement.Youswitchamongareaswithin theeditorjustasyouwouldbetweentheNavigationpanelorRecentElementstaband theeditor.Toselectadifferentarea,clickanywhitespaceinthatarea.Todisplaythe contentsofatab,clickthetabname.

webMethods Developer Users Guide Version 7.1.1

27

1 Getting Started with Developer

Editing controls for an element

If you open an element from the Navigation panel...

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.

...editing controls for that element are displayed in the editor.

Asmentionedearlier,youcanusetheNavigationpanelandRecentElementstabtoselect oneormoreelementstovieworeditintheeditor.Itishelpfultodisplaymultiple elementsintheeditorwhenyouareeditinganelementandyouwouldliketoreferback toanotherelementforinformation.Forexample,ifyouarecreatingoreditinga Broker/localtrigger,youmaywanttoquicklyviewthedocumenttypesandservices associatedwiththattrigger. Eachelementyouopenhasitsowntabintheeditor.Theelementstitlebarcontainsthe fullyqualifiednameoftheelementandiconstoindicatetheelementstypeandlock status.Formoreinformationabouttheseicons,seeNavigationPanelIconsonpage 22 andWhatIsaLock?onpage 88. Tip! YoucanpressCTRL+ALT+RIGHTARROWtotoggleforwardbetweenopen elementsintheeditorandCTRL+ALT+LEFTARROWtotogglebackward.

28

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

Editor with multiple elements opened

Each opened element in the editor has its own tab. The elements title bar displays the elements fully qualified name. Click to view tabs that are not currently visible.

Click to close the active element (that is, the element that is currently displayed).

Some elements have specialized tabs.

Tip! YoucanlocatetheactiveelementintheNavigationpanelbyusingthe EditLocate in Navigationcommand.

The Properties Panel

ThePropertiespaneldisplaysthepropertiesforthecurrentlyselectediteminthe Developerwindow.Youusethispaneltoviewandeditthepropertiesofanitem(suchas anelement,astepinaflowservice,afieldinadocument,oralinkbetweentwo variables). ThepropertiesthatDeveloperdisplaysinthispanelvarydependingontheitemyou selectandwhichareaoftheDeveloperwindowhasthefocus.Developeridentifiesthe itemforwhichpropertiesaredisplayedbeneaththetitlebarofthePropertiespanel. Tip! IfthePropertiespaneldisplaysthepropertiesforanitem(forexample,a documentfield)andyouwanttodisplaythepropertiesforitsparentelement(for example,thedocumenttypetowhichthefieldbelongs),clickthetitlebarofthe parentelementintheeditor,thetaboftheparentelementintheeditor,orthewhite spacewithintheeditor.

webMethods Developer Users Guide Version 7.1.1

29

1 Getting Started with Developer

Properties panel
Drag to resize the Property and Value columns.

Click to collapse the list of properties beneath a category.

Name of the item for which properties are displayed. Properties are grouped into categories.

Click to expand the list of properties beneath a category.

Description of the selected property.

Dependingonthetypeofpropertyyouselect,youeditapropertyby: Typingavalueintheboxtotherightofthepropertyname(forexample,tospecify thenamespaceandlocalnamesthatmakeuptheuniversalnameforaservice) Tip! Youcanalsopastetextintotheboxthatyoupreviouslycopiedtothe clipboard. Note: Developeracceptsthetextyoutypeinapropertyboxwhenyoumovethe focusoutsideoftheboxorpressENTER.Youcancancelyoureditsbeforeyou performeitheroftheseactionsbypressingESC. Selectingavaluefromalist(forexample,tospecifyavalidationprocessingrule) Clickingabuttonnexttothepropertynameandsupplyingvaluesonadialogbox (forexample,tospecifyanindexwhenlinkingtoorfromanarrayvariable) Clickingthebrowse buttontolocateanelement(forexample,aservice)

Thetipsareabeneaththelistofpropertiesincludesadescriptionoftheselectedproperty anditsvalues.Toobtainthisinformationforaparticularproperty,clicktheproperty name. Note: Ifyoudonotownthelockforanelement,theelementspropertiesarereadonly.

30

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

The Results Panel

TheResultspanelshowstheresultofaservicesexecution,thevariablesthataservice addstothepipeline,andthecontentsofthosevariables.Youcanusethispaneltoquickly examinethedataproducedbytheservicewhileyouaretestinganddebuggingthe service.Youcanalsosavethedatatoafileanduseitasinputforalatertest. Results panel

Click a variable name...

...to view its contents in the pipeline at this stage of the services execution.

Formoreinformationaboutserviceexecutionresults,seeChapter 11,Testingand DebuggingServices.

Working in the Developer Window

Moving Between Panels
BeforeyoucanperformanactiononanitemthatisdisplayedintheDeveloperwindow, youmustfirstselectthepanelinwhichthatitemappears(thatis,givethatpanelthe focus).YoucanonlyselectonepanelintheDeveloperwindowatatime.Developer indicateswhichareahasthefocusbyhighlightingtheareastitlebarinblue. ToswitchfromonepaneloftheDeveloperwindowtoanother,clickanywhitespaceor fieldwithinthepaneltowhichyouwanttoswitch.Thisactionchangesthefocustothe newpanelandmakesitsmenucommandsandtoolbarbuttonsavailableforuse.

webMethods Developer Users Guide Version 7.1.1

31

1 Getting Started with Developer

Performing Actions
Beforeyoucanperformanactiononanelement,youmustselecttheelementinoneofthe followingways: Singleclickthetitlebarofanelementintheeditor. Rightclickanelement. SingleclickoneormoreelementsintheNavigationpanel. Tip! Toselectagroupofadjacentelementssimultaneously,presstheSHIFTkeyas youclick.Toselectagroupofnonadjacentelements,presstheCTRLkey. Note: SingleclickinganelementintheNavigationpanelselects(highlights)the elementbutdoesnotopentheelementforviewingoreditingintheeditor.To openanelementintheeditor,doubleclickit. TheactionsthatareavailableforanelementdependonwhichareaoftheDeveloper windowhasthefocus.Forexample,torunaservice,theservicemustbeopeninthe editorandhavethefocus. Thereareanumberofwaystoperformanactiononanelementafteryouselectit: Menu commands.Youcanselectacommandfromthemenubartoperformanactionon anelement.Forexample,tosavechangestoanopenedelementusingthemenubar, selecttheelementintheeditorandthenclickFileSave. Youcanalsoaccessmenucommandsonashortcutmenubyrightclickingthe element.Forexample,toopenanelementusingashortcutmenu,rightclickthe elementintheNavigationpanelandthenclickOpen.Tocloseaneditorusinga shortcutmenu,rightclicktheeditortitlebarandthenclickClose Active Editor. Toolbar buttons.Youcanclickatoolbarbuttontoperformanactiononanelement.For example,tosavechangestoanopenedelementusingatoolbarbutton,selectthe elementintheeditorandthenclick . Thetoolbarbuttonsthatareavailableforyoutousedependontheiteminthe Developerwindowthatcurrentlyhasthefocus.Forexample,whenyouareeditinga flowservice,theflowservicetoolbarbuttonsintheeditorarenotavailableunlessthe editorhasthefocus. Keys.YoucanusethekeyboardtoaccessamenubypressingtheALTkeyplusthe underlinedletterinthemenuname.Youcanthenselectacommandonthatmenuby pressingtheunderlinedletterinthecommandstitle.Forexample,tosavechangesto anelementusingthekeyboard,selecttheelement,pressALTandFtoaccesstheFile menu,andthenpressStosavetheelement. Somecommandsalsohaveshortcutsassignedtothem.Theseshortcutsaredisplayed totherightoftheirassociatedcommandsonthemenubar.Forexample,tosave changestoanelementusingakeyboardshortcut,selectthatelementandthenpress CTRLandS.

32

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

Drag-and-drop action.Youcanselectanelementandmoveittoanotherpackageor element,eitheronthesameserveroronadifferentserver,bydraggingit.For example,tomoveanISdocumenttypefromonefoldertoanother,youwoulddrag thatdocumenttypetothenewfolder. Note: Someelements,suchasadapternotifications,cannotbemovedusingthe draganddropaction. Mostoftheproceduresinthisguideinstructyoutoperformactionsusingmenu commands.

Resizing Areas in the Developer Window

YoucanresizeareasintheDeveloperwindowby: Hidingorshowingpanels Draggingthemovableborderbetweenpanels Switchingperspectives

Hiding and Showing Panels

YoucanhideandshowpanelsontheDeveloperwindowasfollows: To... HidetheNavigationpanel, UDDIRegistrytab,and RecentElementstab ShowtheNavigation panel,UDDIRegistrytab, andRecentElementstab HidethePropertiesand Resultspanels Click alongtherightedgeoftheDeveloperwindow. ShowthePropertiesand Resultspanels Click Expandorcollapseeditor details alongtherightedgeoftheDeveloperwindow. Do this...

Click

alongtheleftedgeoftheDeveloperwindow.

Click

alongtheleftedgeoftheDeveloperwindow.

Click ontheborderbetweenthetopoftheeditorand thespecializedtabsbeneathit.

Dragging Movable Borders

YoucanresizeareasintheDeveloperwindowbydraggingthemovablebordersbetween panelswithyourmouse.

webMethods Developer Users Guide Version 7.1.1

33

1 Getting Started with Developer

Switching Perspectives
YoucanquicklychangetheDeveloperwindowtotailorittothetaskyouareperforming (forexample,showonlytheeditorandResultspanelwhenyouaretestingaservice)by displayingaparticularperspective.PerspectivesallocatemorespaceontheDeveloper windowforaparticulartaskbyhidingorminimizingtheareasthatarenotessentialto thattask. Developeroffersthreeperspectives: Edit perspective.TheeditperspectivedisplaysalloftheDeveloperwindowareasbut minimizestheResultspanel.Thisperspectiveisusefulwhenyouareopeningand editingelementsandtheirproperties. Test perspective.ThetestperspectivehidestheNavigationpanel,UDDIRegistrytab, andRecentElementstabandmaximizestheeditorandtheResultspanel.This perspectiveisusefulwhenyouaretestinganddebuggingaserviceandyouwantto viewtheresultsoftheservicesexecution,itsinputsandoutputs,anditspipeline variables. Details perspective.ThedetailsperspectivehidestheNavigationpanel,UDDIRegistry tab,andRecentElementstabandminimizestheResultspanel.Thisperspectiveis usefulwhenyouwanttoseeasmuchofanelementsdetailaspossible(forexample,a servicespipeline). Youdisplayaperspectiveasfollows: To display the... Editperspective Testperspective Detailsperspective Use this command... WindowEdit Perspective WindowTest Perspective WindowDetails Perspective Or click this toolbar button...

Youcanmanuallyadjustareaswithinaperspectiveusingtheothertechniquesdescribed inthissection.Developersavesyoursettingsacrosssessions. Ifyouhaveadjustedtheperspectivesmanuallyandyouwanttorevertthemtotheir defaultsettings,usetheWindowReset Perspectivescommand.

34

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

Resizing areas in the Developer window

Click to hide or show the Navigation panel, UDDI Registry tab and Recent Elements tab. Click to expand or collapse editor details. Click to display Edit, Test, and Detail perspectives. Click to hide or show the Properties and Results panels.

Drag movable borders to resize panels.

Opening, Closing, and Restoring Sessions

WhenyoustartDeveloperyouarepromptedtologontotheserverthatyouwantto access.YoumaintainasessiononthatserveruntilyouexitDeveloperorclosethesession. Youcanhaveopensessionsonmultipleserversatatime.IntheNavigationpanel,the serverthatcontainstheselectedelementistheserveronwhichyourcommandswillbe executed.Forexample,ifyouhavethe localhost:5555serverselectedintheNavigation panelandyouselecttheNewcommand,thenewelementwillbecreatedonthatserver. Youcanopenasessiononanotherserverwithoutclosingyourcurrentsessionbyusing theSessionOpen command. To open a session on a different server 1 2 3 OntheSessionmenu,clickOpen. CompletetheOpenSessiondialogbox.Formoreinformationaboutcompletingthis dialogbox,seeTostartDeveloperonpage 19. ClickOK. Important! WhileyouhaveanopensessiononaserverthroughDeveloper,youare usingalicensedseatforthatserver.Attimeswhenyouarenotactivelyusing Developer,youmaywanttocloseyoursessiontofreeaseatontheserverforothers touse.

webMethods Developer Users Guide Version 7.1.1

35

1 Getting Started with Developer

To close a session on the current server 1 2 Saveanyworkthatyouwanttokeep. OntheSessionmenu,click Close.

Restoring a Session on a Server

Sometimesaservermightshutdownbeforeyoucansaveyourwork.Developer preservesanyunsavedworkaswellaslockinformation,despitethelossofthe connectiontotheserver.Whentheserverrestarts,youcanrestoreyoursessionandsave yourchangestotheserver. Important! Ifaservershutsdownandyoucloseyoursession(thatis,disconnectfrom theserver),closeunsavedelementsonthatserverintheeditor,orexitDeveloper beforetheserverrestarts,Developerwarnsyouthatifyoucontinueyouwillloseall unsavedwork.Ifyoudonotwanttoloseyourwork,clickCancelandwaitforthe connectiontothatservertoberestored.

To restore a session on the server OntheSessionmenu,clickRestore. Note: Restoringasessionisdifferentfromrefreshingthesession.Refreshingthe sessionupdatesyourscreentoreflecttheactionsofotherusersonelementsthatare displayedwithintheNavigationpanelandtheeditors.Arefreshactiondoesnot restoretheworkingstateofanelementifaservershutsdown.Formoreinformation aboutrefreshingtheNavigationpanel,seeRefreshingtheContentsofthe NavigationPanelonpage 25.

Notification of Server Shutdown

Iftheserveradministratorshutsdowntheserveronwhichyouhaveanopensession, Developerdoesoneofthefollowing: Iftheserveradministratorspecifiedatimedelaybeforeshutdown,Developer displaysamessagenotifyingyouwhentheshutdownprocessbeganandhowmany minutesremainbeforetheservershutsdown.Afteryoureceivenotificationofserver shutdown,saveanyworkthatyouwanttokeepandthencloseyoursession.Ifyou donotcloseyoursession,Developernotifiesyouwhentheserverhasshutdown. Iftheserveradministratorperformedanimmediateshutdown,Developerdisplaysa messagestatingthatyourconnectiontotheserverhasbeenlost.(Developeralso displaysthismessageifthenetworkconnectiontotheserverislost.)

36

webMethods Developer Users Guide Version 7.1.1

1 Getting Started with Developer

Ifyoudidnotsaveyourworkbeforeshutdownoccurred,youmightbeabletorestore yoursessionwhentheserverrestartsandthensaveyourwork.Formoreinformation aboutrestoringsessions,seeRestoringaSessiononaServeronpage 36.

Changing Your Password

Youcanchangethepasswordforyouruseraccount.Ifyouforgetyourpassword,contact theserveradministrator. Important! Ifyouareoutsideofthecorporatefirewall,donotchangeyourpassword unlessyouuseSSLtoopenthesessiononthewebMethodsIntegrationServer.Ifyou donotuseSSL,yourpasswordcanbeexposedinunencryptedform. Note: YoucannotuseDevelopertochangepasswordsthatarestoredinanLDAP server.

Password Requirements
Forsecuritypurposes,webMethodsIntegrationServerplaceslengthandcharacter restrictionsonpasswords.webMethodsIntegrationServercontainsadefaultsetof passwordrequirements;however,yourserveradministratorcanchangethese.Formore informationaboutthesepasswordrequirements,contactyourserveradministrator. ThedefaultpasswordrequirementsprovidedbywebMethodsareasfollows: Requirement Minimumlength Minimumnumberofalphabeticcharacters Minimumnumberofuppercasecharacters Minimumnumberoflowercasecharacters Minimumnumberofnumericcharacters Minimumnumberofspecialcharacters(nonalphabeticandnonnumeric characters,suchas*.?,&) Toensurethesecurityofyourpassword,followtheadditionalguidelinesbelow: Donotchooseobviouspasswords,suchasyourname,address,phonenumber, licenseplate,spousesname,childsname,orabirthday. Donotuseanywordthatcanbefoundinthedictionary. Donotwriteyourpassworddown. Donotshareyourpasswordwithanyone. Changeyourpasswordfrequently. Default 8 3 2 2 1 1

webMethods Developer Users Guide Version 7.1.1

37

1 Getting Started with Developer

To change your password 1 2 3 4 OntheSessionmenu,clickChange Password. IntheChangePassworddialogbox,intheOld Passwordfield,typeyourcurrent password. IntheNew Passwordfield,typeyournewpassword. IntheConfirm New Passwordfield,retypeyournewpassword.ClickOK. Important! Theserveradministratorcandisablethefeatureforchangingyour passwordfromDeveloper.Ifthefeatureisdisabledandyoutrytochangeyour password,youwillreceiveamessagestatingthattheadministratorhasdisabledthe feature.

Using Online Help

YoucanaccessonlinehelpatanypointinwebMethodsDeveloper.Toopenthehelp systemandsearchforatopicofinterest,clickContentsfromtheHelpmenu.Developer alsoprovidesthefollowingtypesofcontextsensitivehelp: Window areas. ForhelpaboutthedialogboxorDeveloperwindowareathatcurrently hasthefocus,dooneofthefollowing:

ClicktheHelpbutton(availableinmostdialogboxes). PressF1. FromtheHelpmenu,clickOn Topic. OntheDeveloperwindowtoolbar,click .

Properties. Forhelpaboutaproperty,clickthepropertyinthePropertiespanel. DeveloperdisplaysadescriptionofthepropertyatthebottomoftheProperties panel. Built-in services.ForadescriptionofabuiltinservicewithintheWmART,WmDB, WmPKI,WmPRT,orWmPublicpackages,dooneofthefollowing:

IfyouarebrowsingtheserviceswithinapackageintheNavigationpanel,selecta serviceandpressF1. IfyouhaveaddedabuiltinservicetoaflowserviceusinganINVOKEstep,select thebuiltinserviceintheeditorandpressF1. Ifyouarebrowsingforabuiltinservicetoaddtoaflowservice,selectthebuiltin serviceintheSelectdialogboxandpressF1.

Youcanalsovieworprintdescriptionsofallbuiltinservicesfromonelocationby clickingHelpBuilt-In Service Reference.

38

webMethods Developer Users Guide Version 7.1.1

Managing Elements in the Navigation Panel

40 41 43 44 45 47 51 53 53 55 60 63 66

What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

39

2 Managing Elements in the Navigation Panel

What Is an Element?
AnelementisanitemthatexistsintheNavigationpanelinwebMethodsDeveloper. Elementsincludefolders,services,specifications,ISdocumenttypes,triggers,andIS schemas.IntheNavigationpanel,serversandpackagesarenotconsideredtobe elements. Elements in the Navigation panel

Folders, services, triggers, specifications, IS document types, and IS schemas are elements.

Thefollowingtableidentifieswheretogoformoreinformationaboutcreatingnew elementsandperformingactionsonthoseelements. For information about... Creating,opening,movingand copying,renaming,deleting, finding,andcachingelements Lockingelements Checkingelementsintoandoutofa thirdpartyversioncontrol repository Performingactionsonpackages See... Thesectionsinthischapter

Chapter 4,LockingandUnlockingElements webMethodsVersionControlSystemIntegration DevelopersGuideinthedirectory: webMethods_directory\_documentation Chapter 3,WorkingwithPackages

40

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Creating New Elements

Whencreatingelements,keepthefollowingpointsinmind: YoucannotcreateanewJavaorCserviceunlessallservicesofthosetypesare unlocked,orlockedbyyou,inthefolderinwhichyouwanttocreatethenewservice. Fordetails,seeLockingJavaandC/C++Servicesonpage 91. Thenamesofnonfolderelementsmustbeuniqueacrossallpackages.Ifyoutryto createanelementusinganamethatalreadyexistsatthatlevelinanypackage, DevelopercreatestheelementandnamesitUntitled. Developerplacessomerestrictionsonthecharactersyoucanuseinelementand packagenames.Formoreinformationabouttheserestrictions,seeGuidelinesfor NamingElementsonpage 42. To create a new element 1 2 3 OntheFilemenu,clickNew. OntheNewdialogbox,clickthetypeofelementyouwanttocreateandthenclick Next. FollowthepromptsgivenbyDeveloperforthetypeofelementyouarecreating. WhenyouhavesuppliedalloftheinformationthatDeveloperneedstocreatethe element,theFinishbuttonbecomesactive. 4 ClickFinish. Tip! Youcanquicklycreateanelementbyclicking nexttotheNewbuttononthe toolbarandthenclickingtheelementyouwanttocreate.Developeraddstheelement beneaththecurrentlyselectedelement,withadefaultnameofUntitled. Ifyouselectmultipleelementsandthenclickthisbutton,DeveloperoffersonlytheAll Choicesoption,whichopenstheNewdialogboxdescribedintheprocedureabove.

About Element Names

ThefullyqualifiednameofanIntegrationServerelementiscomposedoftwoparts:a folderidentifier,consistingofthefolderpathinwhichtheelementresides,andtheelement name.TheIntegrationServerrepresentselementsinthefollowingformat: folder.subfolder1.subfolder2:element Forexample,iftheHomeLoanserviceisinthePersonalfolder,whichiscontainedinthe Financefolder,thefullyqualifiedservicenameis: Finance.Personal:HomeLoan

webMethods Developer Users Guide Version 7.1.1

41

2 Managing Elements in the Navigation Panel

Note: Developerensuresthatthefullyqualifiednameofeachelementwithinthe serverisunique.Dependingontheactionyouareperformingontheelement, Developeraccomplishesthiseitherbyalertingyouthattheactioncannotbe completedorbyappendinganumbertothenameoftheelementaftertheactionis performed.Forexample,ifyouarecopyingaflowservicenamedcheckOrder2toa destinationthatalreadycontainsaflowservicewiththatname,Developercopiesthe serviceandnamesthecopycheckOrder2_1.

Package Names and Element Names

Thenameofthepackagetowhichanelementbelongshasnobearingonthenamesofthe elementsthatpackagecontains(thatis,thepackagenameisnotpartofthefullyqualified nameoftheelement).Nordoesitaffecthowtheelementisreferencedbyaclient application.Forexample,ifyoumoveaservicecalledPersonnel:GetDeptNamesfroma packagecalledAdmintoapackagecalledEmployeeData,clientapplicationswouldstill referencetheserviceasPersonnel:GetDeptNames.

Guidelines for Naming Elements

webMethodsDeveloperplacessomerestrictionsonthecharactersyoucanuseinelement andpackagenames.Specifically,elementandpackagenamescannotcontain: ReservedwordsandcharactersthatareusedinJavaorC/C++(suchasfor,while,and if ) Digitsastheirfirstcharacter Spaces Controlcharactersandspecialcharacterslikeperiods(.),including: ? & % ' @ * ^ : # ! $ = | ] ) } [ ( { " . ` + / > , \ < ~ ;

CharactersoutsideofthebasicASCIIcharacterset,suchasmultibytecharacters Ifyouspecifyanamethatdisregardstheserestrictions,Developerdisplaysanerror message.Whenthishappens,useadifferentnameortryaddingaletterornumbertothe nametomakeitvalid.

42

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Editing Elements
Toeditanelement,youmustfirstlockit.YoumustalsohaveWriteaccesstotheelement. Formoreinformationaboutlockingandunlockingelements,seeChapter 4,Locking andUnlockingElements.Formoreinformationaboutaccesspermissions,seeChapter 5, AssigningandManagingPermissions. IfyouhaveenabledtheVCSIntegrationfeature,youmustfirstcheckouttheelement beforeyoucaneditit.Formoreinformation,seethewebMethodsVersionControlSystem IntegrationDevelopersGuideinthewebMethods_directory\_documentationdirectory. Tip! YoucanproduceprintableversionsofmanyoftheelementsintheNavigation panelbyclickingFileView as HTML.

Specifying Dependency Checking Safeguards

Developerautomaticallychecksfordependentswhenyoudelete,rename,ormove elementsintheNavigationpanel.Thisdependencycheckingactsasasafeguardto preventyoufrominadvertentlyaffectingotherelementsonthewebMethodsIntegration Server.Thisisespeciallyimportantduringcollaborativedevelopmentonthesame webMethodsIntegrationServer. YoucanhaveDeveloperpromptyoubeforedeleting,moving,orrenaminganelement withdependents.YoucanalsohaveDeveloperupdatelocalreferenceswhenpasting elements. Note: Thedependencycheckingoptionsareenabledbydefault.

To specify dependency checking safeguards 1 2 OntheToolsmenu,clickOptions. ClickGeneral.Under Navigation Panel,dothefollowing: Select... Confirm before deleting To... InstructDevelopertonotifyyoubeforedeletinganelement usedbyotherelements,suchasflowservices,ISdocument types,specifications,ortriggers. IfDeveloperfindselementsthatdependontheelement beingdeleted,Developerliststhosedependentsand promptsyoutodeletetheelementanywayorcancelthe action.Ifyouclearthischeckbox,Developerdeletesthe elementwithoutpromptingyou.

webMethods Developer Users Guide Version 7.1.1

43

2 Managing Elements in the Navigation Panel

Select... Prompt before updating dependents when renaming/moving

To... InstructDevelopertoalertyouwhendependents(thatis, otherelementsthatusetheselectedelement,suchasflow services,ISdocumenttypes,ortriggers)exist. Ifdependentsexist,Developerliststhosedependentsbefore renamingormovingtheselectedelementandpromptsyou to: Rename/movetheselectedelementandupdate referencesindependentelements. Rename/movetheselectedelementwithoutupdating referencestoit. Canceltheaction. Ifyouclearthischeckbox,Developerautomaticallyupdates dependentswithoutpromptingyou.

Update local references when pasting multiple elements 3 ClickOK.

InstructDevelopertoupdatereferenceswhencopyingand pastingagroupofelementsthatrefertoeachother. Ifyouclearthischeckbox,Developerretainstheoriginal referencesinthecopiedelements.

Formoreinformationaboutfindingdependents,seeFindingDependentsand Referencesonpage 60.

Notes About Performing Actions on Elements

Whenperformingactionsononeormoreelements,keepthefollowingpointsinmind: YoumusthaveatleastListaccesstoviewelements,Readaccesstoselectelementsto moveorcopy,Writeaccesstothelocationtowhichyouwanttomove/copyelements, andWriteaccesstoelementsyouwanttorenameordelete.Ifyouselectmultiple elementsandyoudonothavetherequiredaccesstooneormoreofthem,youwill notbeabletoperformtheaction.Youmusteitheraskyoursystemadministratorto giveyoutherequiredaccesstotheelementsorselectonlyelementsforwhichyou havetheproperaccess. Developerpromptsyoutosavechangestoanelementbeforeallowingyouto performanactionontheelement,closetheelementintheeditor,closeyoursession onthecurrentserver,orexitDeveloper. Theactionsyoucanperformonitemsdependonthetypeandcombinationofitems youselect.Ifanactionisnotallowedforoneormoreelementsinaselection, Developermakestheactionunavailableforuse.Forexample,Developerdisablesthe cut,copy,paste,anddeleteactionsifyouselectaserver.Developeralsopreventsyou

44

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

fromselectingmultipleelementswhendoingsocouldcauseconfusionorundefined results.Forexample,youcannotselectaserverandanyotherelement,apackageand anyotherelement,orafolderandoneormoreelementscontainedwithinthatfolder. IfyouselectmultipleelementsandDeveloperencountersanerrorwhileperforming thespecifiedactionononeormoreoftheelements,Developerdisplaysadialogbox listingtheelementsforwhichtheactionfailed.Youcanobtainmoreinformation aboutwhytheactionfailedbyclickingDetails. Theelementsyouwanttomove,copy,rename,save,ordeletemustbeunlocked,or lockedbyyou.Formoreinformationaboutlockingandunlockingelements,see Chapter 4,LockingandUnlockingElements. Youcannotundoamove,copy,rename,ordeleteactionusingtheEditUndo command. Ifyouselectapublishabledocumenttypethatisassociatedwithanadapter notification,Developerhandlesactionsperformedonthedocumenttypeasfollows:

Fornoncopyactions,youmustalsoselecttheadapternotificationbeforeyoucan performanoncopyactiononthedocumenttype. Forcopyactions,youcanselectthepublishabledocumenttypewithoutselecting itsassociatedadapternotification.However,thecopiedpublishabledocument typelosesitsassociationwiththeadapternotification.

Opening and Closing Elements in the Editor

YoucanopenelementsfromeithertheNavigationpanelortheRecentElementstab. WhenopeningelementsfromtheNavigationpanel,keepthefollowingpointsinmind: Singleclickinganelementselectstheelementbutdoesnotdisplayitsdetailsinthe editor.Doubleclickinganelementopensitintheeditor. Doubleclickingafolderexpandsorcollapsesthecontentsofthefolderinthe Navigationpanel.ToviewafolderspropertiesinthePropertiespanel,performthe stepsintheprocedurethatfollows. IftheDevelopersVersionControlSystem(VCS)Integrationfeatureisenabled, Developermightexhibitslowdowns,errormessages(suchasServerversionhas changedandSessionalreadyinuse),andmaystoprespondingcompletelywhen youexpandalargeelement(suchasafolder)intheNavigationpanel.Thiscondition occurswhenDeveloperqueriestheIntegrationServertocheckthelockstateofeach elementwithinanelement.Toimproveperformanceduringlockchecking,see OptimizingLockCheckingonpage 73.

webMethods Developer Users Guide Version 7.1.1

45

2 Managing Elements in the Navigation Panel

To open elements in the editor 1 Selectoneormoreelementstoopen. Tip! PresstheSHIFTkeyasyouclicktoselectagroupofadjacentelements.Press theCTRLkeytoselectagroupofnonadjacentelements. 2 OntheFilemenu,clickOpen. IfyouareopeninganelementfromtheRecentElementstabandtheelementresides onaservertowhichyouarenolongerconnected,Developerpromptsyoutologonto thatserverbeforedisplayingtheelement. To close elements in the editor Dooneofthefollowing: To... Closetheactiveelementintheeditor (thatis,theelementwhosetabis highlighted) Closeallelementsexcepttheactiveone Closeallelementsintheeditor Do this... OntheWindowmenu,clickClose Active Editor. OntheWindowmenu,clickClose All But Active Editor. OntheWindowmenu,clickClose All Editors.

Note: YoudonotneedtocloseelementswhenyouexitDeveloper.Developer rememberswhichelementswereopenanddisplaysthemwhenyourestart Developer.Ifyoucloseanelementwithoutsavingchangesmadetotheelement, Developerwillpromptyoutosavechanges.

46

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Moving and Copying Elements

Youcanmoveorcopyelementsbetweenpackagesand,inmostcases,acrossservers. Whenmovingorcopyingelements,keepthefollowingpointsinmind:

General
YoumusthaveReadaccesstotheelementsyouaremovingorcopyingandWrite accesstothepackages,folders,orserverstowhereyouwanttomove/copythem.For moreinformationaboutWriteaccessandACLsassignedtoelements,seeChapter 5, AssigningandManagingPermissions. Whenyoumoveorcopyanelement,Developerautomaticallychangestheelements fullyqualifiednametoreflectitsnewlocation. Youcannotmoveanelementtoalocationthatalreadycontainsanelementwiththe samename.Ifyoucopytheelement,however,Developercopiestheelementand appendsanumbertotheendofthenameofthecopiedelement. Youcannotmovemultipleelementswiththesamenametoasinglelocation. Afteryoumoveorcopyanelement,theelementbecomeslockedbyyou. Whenyoucopymultipleelementstoanotherlocationonthesameserverandthe elementscontainreferencestoeachother,Developerupdatesthereferencesifyou haveselectedUpdate local reference(s) when pasting multiple elementsontheOptions dialogbox.Forexample,ifyoucopyafolderthatcontainstwoservicesandoneofthe servicesinvokestheother,Developerwillupdatethereferencetotheinvokedservice.

Moving and Copying Services

Whenyoumoveorcopyaservice,Developerdoesnotmove/copyanyoutput templatesthatareassociatedwiththatservice. Ifyoumoveaservice,orafoldercontainingaservice,Developerretainstheservices explicituniversalname.Ifyoucopyaserviceorafoldercontainingaservice, Developerdoesnotretaintheservicesexplicituniversalname.Youmustrestorethe universalnamebyeditingtheservicesproperties.Formoreinformation,see AssigningUniversalNamestoServicesonpage 137. WhenyoumoveorcopyaJavaservice,Developerautomaticallyrecompilesthe serviceandanyJavaservicesthatremaininthesourcefolder.WhenyoudeleteaJava service,DeveloperrecompilesanyJavaservicesthatremaininthesourcefolder.

webMethods Developer Users Guide Version 7.1.1

47

2 Managing Elements in the Navigation Panel

YoucannotmoveorcopyaJavaservicetoafolderthatcontainsotherJavaservices thataresystemlockedorlockedbyanotheruser.Ifyouattempttodoso,Developer cancelstheentiremove/copyaction. WhenyoumoveorcopyaJavaservice,Developerwillalsomoveorcopytheservices Sharedfieldstothedestinationfolder,unlessthedestinationfolderalreadycontains Sharedfieldswithdifferentvalues.Inthiscase,youmustfirstmanuallycopythe SharedfieldsintothedestinationfolderandthenmoveorcopytheJavaservice.

Copying Elements Between Servers

YoucannotcopyormoveaWebservicedescriptorelementbetweenservers. Whenyoucutandpasteordragelementsbetweenservers,Developerretainsacopy oftheelementsonthesourceserver.Thatis,amove(cutandpasteordrag)actionis thesameasacopyaction. Developerdoesnotautomaticallycopyanelementsreferencestothedestination server.Instead,itdisplaysadialogboxafterthecopyalertingyoutoanyunresolved references.Youmustcopythereferencestothedestinationservermanually. Developerdoesnotautomaticallyupdatereferenceswhencopyingacrossservers. Therefore,ifyouarecopyingmultipleelementsfromoneservertoanotherusing Developerandtheelementsreferenceeachother,youshouldpastetheelementsinto alocationwiththesamenameonthedestinationserver. Ifyouarecopyinganaddinelementthathasacomponentthatresidesontheserver, andthedestinationserverdoesnothavethataddincomponentinstalled,Developer displaysanerrormessagestatingthatyouareattemptingtocopyanunknown element.Developerdoesnotcopytheaddinelementsbutdoescopyotherelements intheselection. ElementsyoucopytoafolderonadifferentserveradopttheACLaccesspermissions ofthedestinationfolder,eveniftheyhadexplicitlyassignedACLsonthesource server.FoldersyoucopytoapackageonadifferentserverinheritthedefaultACLs fortoplevelfolders. WhenyoucopyaBroker/localtriggertoanotherserver,thetriggerwillbepastedina disabledstate.Tocreatethesubscriptionsidentifiedinthetrigger,youmustenable thetrigger.Whenyoucopyapackagetoanotherserver,thetriggerscontainedinthe packagewillmaintaintheiroriginalstate. Ifyouareconfiguringacluster,usethepackagereplicationfeatureintheIntegration ServerAdministratortopopulatetheclusternodes.SeethewebMethodsIntegration ServerAdministratorsGuideformoreinformationaboutthisfeature. Whenyoumoveorcopyapublishabledocumenttypetoadestinationonthesame server,themovedorcopieddocumenttyperemainspublishable.Whenyoucopya publishabledocumenttypetoadifferentserver,Developerconvertsthepublishable documenttypetoanISdocumenttypeonthedestinationserver.Formore informationaboutmakingISdocumenttypespublishableandsynchronizingthem withBrokerdocumenttypes,seethePublishSubscribeDevelopersGuide.

48

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Tip! ToretainthestatusofapublishabledocumenttypeanditslinktoaBroker documenttype,usethepackagereplicationfunctionalityintheIntegrationServer AdministratorinsteadofusingDevelopertomoveorcopythepackage containingthepublishabledocumenttype.Forinformationaboutpackage replication,seethewebMethodsIntegrationServerAdministratorsGuide.

Moving and Copying Adapter Notifications and Related Elements

Althoughyoucannotmoveanadapternotificationspublishabledocumenttype withoutalsomovingitsassociatedadapternotification,youcancopyit.Ifyoudoso, thecopieddocumenttyperemainspublishablebutisnolongerassociatedwiththe adapternotification. Whenyoumoveorcopyanadapternotification,Developeralsomoves/copiesits associatedpublishabledocumenttypeandpromptsyoutoindicatewhetherto move/copytheassociatedBrokerdocumenttype. Youcannotmoveorcopyadapternotifications,adapternotificationpublishable documenttypes,oradapterservicesacrossservers.Ifyouareselectingmultiple elementsandyourselectioncontainsanyoftheseelements,Developeralertsyouthat themove/copyactioncannotbecompleted. Youcannotmoveorcopyalistenerorconnectionelement. To move or copy elements 1 2 Selecttheelementsthatyouwanttomoveorcopy. Dooneofthefollowing: To... Cuttheelement Copytheelement Click... EditCut EditCopy

Tip! YoucancancelacutactionbypressingESC. 3 Iftheelementsyouwanttomoveorcopycontainunsavedchanges,Developeralerts youthatyoumustfirstsavethechanges.ClickOKtoclosethealertdialogbox.Then, savethechangesandrepeatthemove/copyaction. IfyoudonothaveReadaccesstotheelementsyouaremovingorcopying,orWrite accesstothelocationyouaremoving/copyingthemto,Developerdisplaysamessage thatidentifiestheelementsthatarepreventingtheactionfromcompleting successfully.ClickOKandtheneitherobtaintheproperaccessfromyoursystem administratororselectonlythoseelementstowhichyouhaveproperaccess. Selectthelocationwhereyouwanttomoveorcopytheelements.

webMethods Developer Users Guide Version 7.1.1

49

2 Managing Elements in the Navigation Panel

6 7

OntheEditmenu,clickPasteAfter. Ifthedestinationalreadycontainsanelementwiththesamenameasanelementyou aremovingorcopying,dooneofthefollowing:

Ifyouaremovingtheelement,Developeralertsyouthattheelementcannotbe moved.ClickOKtoclosethealertdialogbox.Renametheelementifdesiredand repeatthemoveaction. Ifyouarecopyingtheelement,Developercopiestheelementandappendsa numbertothenameofthecopiedelement.(Forexample,ifyouarecopyinga flowservicenamedcheckOrder2toadestinationthatalreadycontainsaflow servicewiththatname,Developercopiestheserviceandnamesthecopy checkOrder2_1.)Renametheelementifdesired.

Formoreinformationaboutrenamingelements,seeRenamingElementson page 51. 8 IfoneoftheelementsyoumovedorcopiedisaJavaservice,performthefollowingas necessary:

IfyouaremovingorcopyingtheJavaservicetoafolderwithotherJavaservices thataresystemlockedorlockedbyanotheruser,Developeralertsyouthatthe elementcannotbemoved/copied. ClickOKandthenasktheownerofthelocktoremovethelock.

IftheJavaserviceyouaremovingorcopyingcontainsasharedsourcethat conflictswiththesharedsourceofanexistingJavaserviceinthedestination folder,Developeralertsyouthatthereisaconflict.ClickOKtousethedestination folderssharedsource,orclickCanceltocanceltheentiremoveaction. Note: IfnosharedJavasourceconflictexists,DevelopermovestheJavaservice anditssharedsourcetothedestinationfolder.Ifaconflictdoesexist,you mustrespecifytheSharedtabinformationinthecopyoftheservice.(Youcan copytheinformationfromtheSharedtabfortheoriginalservicetotheShared tabforthecopyoftheservice.)

IfyouclickedthePrompt before updating dependents when renaming/movingcheckboxin theOptionsdialogboxandanyelementsonthecurrentservercontainunsaved changes,Developerpromptsyoutosavetheelement(s).Dooneofthefollowing: To... Savechangesandthenproceedwiththemove/copyaction Continuethemove/copyactionwithoutsavingchanges Canceltheentiremove/copyaction Click... Save and Proceed Proceed without Save Cancel

50

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

10 IfyouclickedProceed without SaveinStep9,Developeridentifiestheelementsthatwill beaffectedbythemove.Dooneofthefollowing: To... Movetheselectedelementandupdatereferencesto dependentelements MovetheselectedelementintheNavigationpanelwithout updatingreferencestodependentelements Canceltheentiremoveaction Click... Update Usages Ignore Usages Cancel

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 43. Tip! Youcanalsomoveelementsbyclickinganddraggingthemtotheirnewlocation.

Renaming Elements
Whenrenamingelements,keepthefollowingpointsinmind: YoucanrenameanyelementsforwhichyouhaveWriteaccesstotheelementandits parentfolder.Whenrenamingafolder,youmustalsohaveWriteaccesstoall elementswithinthefolder.FormoreinformationaboutWriteaccessandACLs assignedtoelements,seeChapter 5,AssigningandManagingPermissions. Whenyourenameafolder,Developerautomaticallyrenamesalloftheelementsin thatfolder(thatis,changestheirfullyqualifiednames). Ifthefolderyouwanttorenamecontainselementswithunsavedchanges,youmust savethechangesbeforeyoucanrenamethefolder. Elementnamesmustbeuniqueacrossallpackages.Ifyoutrytorenameanelement usinganamethatalreadyexistsatthatlevelinanypackage,Developerrevertsthe elementbacktoitsoriginalname. Whenyourenameanadapternotification,Developeralsorenamesitsassociated publishabledocumenttypeandpromptsyoutoindicatewhethertorenamethe associatedBrokerdocumenttype. Youcannotrenamealistenerorconnectionelement.

webMethods Developer Users Guide Version 7.1.1

51

2 Managing Elements in the Navigation Panel

To rename an element 1 2 3 Selecttheelementthatyouwanttorename. OntheEdit menu,clickRename. Iftheelementyouwanttorenamecontainsunsavedchanges,Developeralertsyou thattheelementcannotberenameduntilyousavethechanges.ClickOKtoclosethe alertdialogbox.Then,savethechangesandrepeattherenameaction. Developermovesthecursortotheendoftheelementname.Editthenameandpress ENTER. Ifanelementalreadyexistswiththatnameatthesamelevel,Developerdisplaysa messagealertingyouthattherenameactioncouldnotbecompleted.ClickOKtoclose themessagedialogboxandrepeattherenameaction. Tip! YoucancancelarenameactionbypressingESC. 5 IfyouclickedthePrompt before updating dependents when renaming/movingcheckboxin theOptionsdialogboxandanyelementsonthecurrentservercontainunsaved changes,Developerpromptsyoutosavetheelement(s). Dooneofthefollowing: To... Savechangesandthenproceedwiththerenameaction Proceedwiththerenameactionwithoutsavingchanges Canceltheentirerenameaction 6 Click... Save and Proceed Proceed without Save Cancel

IfyouclickedProceed without SaveinStep5,Developeralertsyoutotheelementsthat willbeaffectedbytherenameaction. Dooneofthefollowing: To... RenametheselectedelementintheNavigationpaneland updatereferencestodependentelements Renametheselectedelementwithoutupdatingreferencesto dependentelements Canceltheentirerenameaction Click... Update Usages Ignore Usages Cancel

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 43.

52

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Saving Changes to Elements

ChangesthatyoumaketoanelementarenotwrittentowebMethodsIntegrationServer untilyouexplicitlysaveyourwork. To save changes to elements Dooneofthefollowing: To... Savechangestothecurrentelement Saveallelementsyouhaveedited,onall servers Do this... OntheFile menu,clickSave. OntheFile menu,clickSave All Editors.

IfyouattempttocloseDeveloper,closeyoursessiononthecurrentserver,closean unsavedelementintheeditor,orperformanactiononanelementwithoutsavingyour changes,Developerwillpromptyoutosavechangesfirst.

Deleting Elements
Whendeletingelements,keepthefollowingpointsinmind: YoucandeleteanyelementstowhichyouhaveWriteaccessfortheelementandits parentfolder.Whendeletingafolder,youmustalsohaveWriteaccesstoallelements withinthefolder.FormoreinformationaboutWriteaccessandACLsassignedto elements,seeChapter 5,AssigningandManagingPermissions. WhenyoudeleteafolderorthelastJavaserviceinafolder,Developeralsodeletesthe sharedsourceforthatfolder.Ifyoucancelthedeleteaction,noelements(including nonJavaserviceelements)aredeleted. Youcanonlydeleteanadapternotificationspublishabledocumenttypeifyoudelete itsassociatedadapternotification. Whenyoudeleteanadapternotification,Developeralsodeletesitsassociated publishabledocumenttypeandpromptsyoutoindicatewhethertodeletethe associatedBrokerdocumenttype. Youcannotdeletealistenerorconnectionelement.

webMethods Developer Users Guide Version 7.1.1

53

2 Managing Elements in the Navigation Panel

To delete elements 1 2 3 Selecttheelementsthatyouwanttodelete. OntheEditmenu,clickDelete. IfyouselectedtheConfirm before deletingcheckboxintheOptionsdialogbox,dothe following: a Ifanyelementsontheservercontainunsavedchanges,Developerpromptsyouto savetheelement(s).Dooneofthefollowing: To... Savechangesandthenproceedwiththedeleteaction Proceedwiththedeleteactionwithoutsaving changes Canceltheentiredeleteaction b c Click... Save and Proceed Proceed without Save Cancel

Iftheelementsyouaredeletingarenotdependentsofotherelements,Developer promptsyoutoconfirmthedeleteaction.ClickOK. Iftheelementsyouaredeletingaredependentsofotherelements,Developer alertsyoutotheelementsthatwillbeaffectedbythedeletion.Dothefollowing: 1 Ifoneoftheelementsyouwanttodeleteisapublishabledocumenttypeoran adapternotification,dooneofthefollowing: To... DeletetheelementontheIntegration Serverbutleavethecorresponding documenttypeontheBroker DeletetheelementontheIntegration Serverandthecorresponding documenttypeontheBroker Do this... CleartheDelete associated Broker document type on the Brokercheck box. SelecttheDelete associated Broker document type on the Brokercheck box.

Important! IfyoudeleteapublishabledocumenttypeandBrokerdocument typeassociatedwithatriggeroraflowservice,youmightbreakany integrationsolutionthatusesthedocumenttype. IfyoudeletetheBrokerdocumenttype,youmightnegativelyimpactany publishabledocumenttypescreatedfromthatBrokerdocumenttypeonother IntegrationServers.Whenthedeveloperssynchronizedocumenttypeswith theBrokerandtheychoosetoPull from Broker,publishabledocumenttypes associatedwiththedeletedBrokerdocumenttypewillberemovedfromtheir IntegrationServers.

54

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Continueorcancelthedeleteactionasfollows: To... DeletetheelementsfromtheNavigationpanel(and thereforebreakanylinkstodependentelements) Canceltheentiredeleteaction Click... Continue Cancel

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 43.

Finding Elements and Fields

YoucanfindelementsandfieldswithinDeveloperusingthefollowingmethods: Find elements in the Navigation panel.Whencreatingandeditingelements,youmight losetrackofwhereyousavedcertainelements.Forexample,supposethatyoudonot rememberthefoldertowhichyousavedaservicecalledTest. Find fields in editor trees.Youcansearchforfieldsincertaintreesintheeditor(thatis, fromwithinadocumentorspecificationeditor,andinaflowservicesPipelinetab). Youmightwanttosearchforfieldswhenworkingwithalargedocumentwithmany fields. Locate an invoked service from the editor.Youcanhighlightthelocationofaninvoked serviceintheNavigationpanel.Thisisespeciallyhelpfulwhenworkingwithaflow writtenbyanotherpartyandwithcomplexflowsthatmakemultipleinvokes.

Finding Elements in the Navigation Panel

UsingtheFindcommand,youcansearchacrossallpackagesandfolderswithinaserver tofindalloccurrencesofaspecifiedelementname. TheFindcommandsearchesthefullyqualifiednamesofelements.Ifyousearchforthe nameTest,theresultsdisplayallelementswithTestintheirfullyqualifiedname.The resultscouldincludeaservicecalledSamplelocatedinaTestfolder,oranISdocument typecalledSampleTest. TheFindcommandinterpretssearchtermsascasesensitiveregularexpressions.By default,thecommandlooksforallelementscontainingaspecifiedsearchterm.For example,ifyouspecifiedTestasasearchterm,theresultswouldincludeelements

webMethods Developer Users Guide Version 7.1.1

55

2 Managing Elements in the Navigation Panel

namedTest,MyTest,andTestFinal.Youcanalsoincluderegularexpression operatorcharacters.Forexample: To find... AllelementscontainingPO AllelementsstartingwithPO AllelementsendingwithPO AllserviceswiththeexactnameoflogPO Allelementscontaininglogfollowedbyanytwocharacters(wildcards) Type...

PO ^PO PO$ :logPO$ log..

Foracompletelistofregularexpressionoperatorcharacters,seeAppendix B,Regular Expressions. Note: The Findcommandsupportsregularexpressionsbutnotconditionalstatements. Forexample,youcanspecifyTestasasearchterm,butnotTest OR Test1.

56

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

To find an element in the Navigation panel 1 2 3 4 5 ClickanywhereintheNavigationpanel. OntheEditmenu,clickFind.DeveloperdisplaystheFindInNavigationPaneldialog box. IntheFind In Navigation Panelbox,typeanyportionofthefullyqualifiednameofthe elementthatyouwanttofind. Ifyouwanttolimitthescopeofthesearchtoaspecificpackage,selectthepackagein thePackagelist. ClickFind.TheFindInNavigationPaneldialogboxdisplaystheresultsofthesearch. Results of search for PO
The term PO is found in...

...the names of 33 elements in the Navigation panel. All of these elements contain PO in their fully qualified name.

TojumptoanelementintheNavigationpanel,selectthatelementintheresultsand clickGo To. Note: IfyoureceiveaCouldntfindinNavigationpanelmessagewhenyouclickGo To,youprobablydonothaveListaccesstotheelement.Contactyourserver administratortoobtainaccess. Tip! Foranactiveelementintheeditor,youcanhighlighttheelementslocationinthe NavigationpanelusingtheEditLocate in Navigation command.

webMethods Developer Users Guide Version 7.1.1

57

2 Managing Elements in the Navigation Panel

Finding Fields in Editor Trees

Youcansearchforafieldinanyofthefollowingtreesintheeditor: Treesinadocumentorspecificationeditor TreesinthePipeline In,Pipeline Out,Service In,andService OutareasinthePipelinetabof aflowserviceeditor Whensearchingforfieldsonaneditortree,keepthefollowingpointsinmind: Youcansearchonlyonetreeatatime.Forexample,ifyouwanttofindfieldsthat containthetextnumberinthePipeline InandService InareasofthePipelinetab,search onetree,andthenthenext. YoucanrefineyoursearchbyrequiringDevelopertofindonlyfieldsthatmatchthe capitalizationofthesearchtextorfieldsthatmatchonlythecompletewordspecified asthesearchtext. Youcansearchforaparentandchildfieldcombination.Forexample,ifyouspecify address/streetasthesearchtext,Developersearchesforallinstanceswhereafield namedstreetisachildofadocumentordocumentlistfieldnamedaddress.Ifyou specifycustomerInformation/address/streetasthesearchcriteria,Developer searchesforafieldnamedcustomerInformationthatcontainsafieldnamedaddress whichcontainsafieldnamedstreet.Useaforwardslash(/)toseparatetheparent fieldfromthechildfield. Developerdoesnottreatsearchtextasaregularexpression.Forexample,ifyoutype ^PO,Developersearchesforfieldsthatcontainthetext^PO.Developerdoesnot searchforfieldsthatbeginwiththetextPO. Note: Developerinterpretstheforwardslashcharacter(/)asthedividerbetween thenameofaparentfieldandachildfield.Developerwillnotsearchforafield namethatcontainsaforwardslashcharacter.Forexample,ifyoutypetrue/false asthesearchtext,Developersearchesforafieldnamedfalsethatisachildofa documentordocumentlistfieldnamedtrue.Developerdoesnotsearchforafield namedtrue/false. Developersearchesthetreeasfollows:

Ifyouselectafield,Developerbeginssearchingattheselectedfieldandcontinues tothebottomofthetree.Ifyouhavenotselectedafield,Developerbegins searchingatthetopofthetree. WhenDeveloperfindsafieldthatmatchesthesearchcriteria,Developerselects thefieldinthetree. WhenDeveloperreachesthebottomofthetree,Developerdisplaysamessage askingifyouwouldliketocontinuesearchingfromthetopofthetree. Aftercompletingasearchoftheentiretree,ifDevelopercannotfindamatching field,Developerdisplaysamessagestatingthatthesearchtextwasnotfound.

58

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

To find a field within an editor tree 1 2 3 Selectthetreeinwhichyouwanttosearchforafield. OntheEditmenu,clickFind. IntheFind whatfield,typethetextyouwanttosearchfor.Ifyouwanttosearchfora parentchildfieldcombination,useaforwardslash(/)toseparatetheparentfield fromthechildfield. Tofurtherrefineyoursearch,dooneormoreofthefollowing: To... Findfieldswiththesamecapitalizationasthe textintheFind whatfield Findonlyfieldsthatmatchthecompleteword intheFind whatfield FindfieldsthatcontainthetextintheFind what fieldasalloraportionoftheirname 5 6 Do this... SelecttheMatch casecheckbox. SelecttheMatch whole wordscheck box. CleartheMatch whole wordscheck box.

ClickFind Next.IfDeveloperfindsamatch,itselectsthefieldanddisplaysitonthe Pipelinetab. ClickFind Nexttofindthenextfieldthatmatchesthesearchcriteria.

Locating Invoked Services

Youcannavigatetothelocationofaninvokedserviceinboththeflowview. To find an invoked service 1 2 Intheeditor,selecttheINVOKEstepcontainingtheserviceyouwanttolocate. OntheEditmenu,clickLocate in Navigation.Developerlocatesandselectstheservicein theNavigationpanel.

webMethods Developer Users Guide Version 7.1.1

59

2 Managing Elements in the Navigation Panel

Finding Dependents and References

Beforeperforminganactiononaselectedelement,youcandeterminewhetherother elementswillbeaffectedbythechangebyfindingdependentsandreferencesofthe element.InDeveloper,adependentisanelementthatusesaselectedelement,anda referenceisanelementthatisusedbyaselectedelement.

Finding Dependents
Todeterminehowaselectedelementisusedbyotherelementsontheserver,youcan finddependentsoftheselectedelement.Forexample,supposethattheflowservice ServiceAinvokestheflowservicereceivePO.TheServiceAserviceuses(thatis,isadependent of)thereceivePOservice.IfyoudeletereceivePOfromtheNavigationpanel,ServiceAwill notrun. Dependent elements
This service is a dependent of... ...each of these services.

Duringdebugging,youmightwanttolocateallofthedependentsofagivenserviceorIS documenttype.Or,beforeeditinganISdocumenttype,youmightwanttoknowwhat elements,suchasspecifications,Broker/localtriggers,orflowservices,willbeaffectedby changestotheISdocumenttype.UsetheFind Dependentscommandtofindallthe dependents. Note: DeveloperdoesnotconsideraJavaservicethatinvokesanotherservicestobea dependent.Forexample,ifJavaserviceAinvokesserviceB,andyouinstruct DevelopertofinddependentsofserviceB,serviceAwillnotappearasadependent.

To find dependents of a selected element 1 2 IntheNavigationpanelorintheeditor,selecttheelementforwhichyouwanttofind dependents. OntheToolsmenu,clickFindDependents. TheFindDependentsdialogboxdisplaysthedependentsoftheelement.

60

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Find Dependents dialog box

The services:receivePO service is used by...

...this element.

AfterDeveloperfindsthedependentsoftheselectedelement,youmaydoanyofthe following:

TojumptoanelementintheNavigationpanel,selectthatelementintheresults andthenclickGo To. Toseealldependentsofafounddependent,click nexttotheitemintheresults list. Tolimitthescopeofthesearchtoaspecificpackage,selectthepackageinthe PackagelistandthenclickFind.

Finding References
Todeterminehowaselectedelementusesotherelementsontheserver,youcanfind referencesoftheselectedelement.Forexample,theflowserviceServiceAinvokesthe servicesreceivePO,pub.schema:validate,processPOandsubmitPO.Additionally,initsinput signature,ServiceAdeclaresadocumentreferencetotheISdocumenttype PODocument. TheservicesreceivePO,validate,processPO,andsubmitPO,andtheISdocumenttype PODocument,areusedby(thatis,theyarereferencesof)ServiceA. Elements as references

Each of these services is a reference of ServiceA.

Duringdebuggingofacomplexflowservice,youmightwanttolocatealloftheservices, ISdocumenttypes,andspecificationsusedbytheflowservice.UsetheFind References commandtolocatethereferences.

webMethods Developer Users Guide Version 7.1.1

61

2 Managing Elements in the Navigation Panel

YoucanalsousetheFind Referencescommandtolocateanyunresolvedreferences.An unresolvedreferenceisanelementthatdoesnotexistintheNavigationpanelyetisstill referredtointheservice,ISdocumenttype,orspecificationthatyouselected.The elementmighthavebeenrenamed,moved,ordeleted.Topreventunresolvedreferences, specifythedependencycheckingsafeguards.Formoreinformationaboutthese safeguards,seeSpecifyingDependencyCheckingSafeguardsonpage 43. Note: Developerdoesnotconsiderdocumentreferencestoschematypestobe references,nordoesitconsiderservicesinvokedwithinaJavaservicetobereferences oftheJavaservice.Forexample,ifJavaserviceAinvokesserviceB,andyouinstruct DevelopertofindreferencesforserviceA,serviceBwillnotappearasareferenceofA. To find references of a selected element 1 2 IntheNavigationpanelorintheeditor,selecttheelementforwhichyouwanttofind references. OntheTools menu,clickFindReferences. TheFindReferencesdialogboxdisplaysthereferencesoftheelement.Unresolved referencesareindicatedinbold italics. Find References dialog box
The processPO service uses...

...these elements.

The element in bold italics does not exist in the Navigation panel

AfterDeveloperfindsthereferencesoftheselectedelement,youmaydoeitherofthe following:

TojumptoanelementintheNavigationpanel,selectthatelementintheresults andthenclickGo To. Toseeallreferencesofafoundreference,click nexttotheitemintheresults list.

62

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

Inspecting Pipeline References

ApipelinereferenceiswhereaLink,Drop,orSet Valuepipelinemodifierisassignedtoafield inadocumentreferenceordocumentreferencelistonthePipelinetab.Forexample,inits inputsignature,ServiceAdeclaresadocumentreferencetotheISdocumenttype PODocument.IfServiceAcontainsanINVOKEorMAPstepinwhichafieldinthedocument referenceislinkedtoanotherpipelinevariable,thenthatlinkisapipelinereference.In thefollowingillustrationofthePipelinetab,thelinkbetweenPoNumandnumisa pipelinereference. Pipeline reference

This variable is a reference to the PODocument in the Navigation panel. The link between ONum and num is a pipeline reference.

Pipelinereferencesarealsothoselocationswhereyouassigna

Set Valuemodifierora

Drop Valuemodifiertoafieldinadocumentreferenceordocumentreferencelist.The followingillustrationofthePipelinetabidentifiesthesetypesofpipelinereferences. Examples of pipeline references

This Drop Value modifier and...

... this Set Value modifier are pipeline

WhenyoueditanISdocumenttype,thechangesaffectanydocumentreferenceand documentreferencelistvariablesdefinedbythatISdocumenttype.Thechangesmight makepipelinereferencesinvalid.Forexample,supposetheinputsignatureforServiceA containsadocumentreferencevariablePOInfobasedontheISdocumenttype

webMethods Developer Users Guide Version 7.1.1

63

2 Managing Elements in the Navigation Panel

PODocument.TheISdocumenttypePODocumentcontainsthefieldPONum.Inthepipeline forServiceA,youlinkthePONumfieldtoanotherpipelinevariable.Ifyoueditthe PODocumentISdocumenttypebydeletingthePONumfield,thepipelinereference(the link)forthefieldintheServiceApipelineisbroken(thatis,itisinvalid)becausethe pipelinecontainsalinktoafieldthatdoesnotexist. WhenyoueditanISdocumenttype,youmightwanttocheckalldependentpipeline modifiersforvalidity.YoucanusetheToolsInspect Pipeline Referencescommandto locateanybrokenorinvalidpipelinereferences.Youcanusethiscommandto: Searchforinvalidpipelinereferencesinaselectedflowservice. Searchforinvalidpipelinereferencesinvolvingdocumentreferenceanddocument referencelistvariablesdefinedbyaselectedISdocumenttype. Wheninspectingpipelinereferences,keepthefollowingpointsinmind: Youcaninspectpipelinereferencesinaselectedflowservice.Youcanalsoinspect pipelinereferencesfordocumentreferenceordocumentreferencelistvariablesbased onaselectedISdocumenttype.Thesearchresultsincludeonlyflowservices, documentreferencevariables,ordocumentreferencelistvariablesthatcontain invalidpipelinemodifiers. Valuessetatthetoplevelofadocumentreferenceordocumentreferencelistinthe pipelinearenotconsideredpipelinereferences.(Thatis,a Set Valuemodifier assignedtothedocumentreferenceisnotapipelinereference.)Therefore,ifaSet Valuemodifierassignedtoadocumentreferencecontainsinputvaluesfora nonexistentfield,itwillnotappearinthesearchresultseventhoughitisinvalid. Thesearchresultswillnotshowdatatypeanddimensionalitymismatches.For example,supposethatyoulinkaStringnamedNumbertothePONumStringlist withinthedocumentreferencePODocument.Thisdimensionalitymismatchwillnot appearinthesearchresults. Whenyouinspectpipelinereferencesinaflowservice,Developerinspectsreferences acrossallpackagesonwebMethodsIntegrationServer. WhenyouinspectpipelinereferencesforanISdocumenttype,youcaninspect referencesacrossaspecificpackageorallpackages.

64

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

To inspect pipeline references 1 2 IntheNavigationpanelorintheeditor,selecttheflowserviceorISdocumenttype forwhichyouwanttofindinvalidpipelinereferences. OntheToolsmenu,clickInspect Pipeline References. TheInspectPipelineReferencesdialogboxdisplaysallinvalidpipelinereferencesfor theselectedserviceorISdocumenttype.

Ifyouinspectedaflowservice,thesearchresultscontainallofthedocument referencesthathaveinvalidpipelinereferencesinthatflow. IfyouinspectedanISdocumenttype,thesearchresultscontainalloftheflow servicesthathaveinvalidpipelinereferencestothatISdocumenttype.

Inspect Pipeline References dialog box

The getData flow service contains...

...an invalid reference in its pipeline to the IS document type po_doc.

AfterDeveloperfindsthepipelinereferencesoftheselectedelement,youmaydoany ofthefollowing:

TojumptoanelementintheNavigationpanel,selectthatelementintheresults andthenclickGo To. Tojumptotheunresolvedreferenceinthepipeline,selecttheelementinthe resultsandthenclickFind in Flow. Iftheselectedelementhasmultipleunresolvedreferencesinthesameflow serviceandyouwanttoautomaticallyjumptothenextreferencewithinthe selectedelement,youcanusetheFind Nextcommand.TousetheFind Next command,keeptheInspectPipelineReferencesdialogboxopenandclickEdit Find Next. Iftheselectedelementisadocumenttypeandyouwanttolimitthescopeofthe searchtoaspecificpackage,selectthepackageinthePackagelistandthenclick Inspect.

webMethods Developer Users Guide Version 7.1.1

65

2 Managing Elements in the Navigation Panel

Caching Elements
YoucanimproveperformanceinDeveloperbycachingNavigationpanelelementsthat arefrequentlyused.WhenelementsarelocatedintheDevelopercache,Developerdoes notneedtorequestthemfromtheIntegrationServerandcanthereforedisplaythem morequickly. To cache elements 1 2 3 OntheToolsmenu,clickOptions. IntheOptionsdialogbox,clickGeneral. UnderNavigation Panel,intheNumber of elements to cachebox,typethenumberof elementsthatyouwanttocacheperDevelopersession.Thetotalnumberofcached elementsincludeselementsonalltheserverstowhichyouareconnected. Theminimumnumberofelementsis10.Thehigherthenumberofelements,the morelikelyanelementwillbeinthecache,whichreducesnetworktrafficandspeeds upDeveloper. 4 ClickOK.Thecachingsettingstakeeffectimmediately. IfyouenteranillegalcachesizeDeveloperdisplaysanerrorandresetsthecachesize tothepreviousvalue. Note: Keepinmindthatincreasingthecachereducestheamountofavailablememory. Ifyouexperiencememoryproblems,considerdecreasingthenumberofcached elements.

Clearing the Developer Cache

WhenyoucleartheDevelopercache,youremoveNavigationpanelelementsfrom memoryforallservers.Thefollowingelementsarenotremoved: Flowserviceswithbreakpoints(ifyouwanttocleartheflowservicefromthecache, removethebreakpointandclearthecacheagain) Flowservicesthatarecurrentlybeingdebugged(forexample,ifaservicehasbeen steppedinto) Unsavedelements KeepinmindthatthecacheisautomaticallyclearedwhenyoucloseDeveloperorwhen yourefreshthesessionbyusingtheSessionRefreshcommand.

66

webMethods Developer Users Guide Version 7.1.1

2 Managing Elements in the Navigation Panel

To clear the Developer cache 1 2 3 OntheToolsmenu,clickOptions.DeveloperdisplaystheOptionsdialogbox. ClickGeneral. UnderNavigation Panel,clicktheClear Cache button.Allcachedelementsareremoved frommemory. Note: ClearingcachedelementsfromDeveloperisdifferentfromclearingthecontents ofthepipelinefromwebMethodsIntegrationServercache.Ifyouwanttoclearthe contentsofthepipelinefromaserverscache,seeConfiguringaServicesUseof Cacheonpage 131.

webMethods Developer Users Guide Version 7.1.1

67

2 Managing Elements in the Navigation Panel

68

webMethods Developer Users Guide Version 7.1.1

Working with Packages

70 70 83

What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

69

3 Working with Packages

What Is a Package?
Apackageisacontainerthatisusedtobundleservicesandrelatedelements,suchas specifications,ISdocumenttypes,ISschemas,andoutputtemplates.Whenyoucreatea folder,service,specification,ISdocumenttype,ISschema,oroutputtemplate,yousaveit inapackage. Packagesaredesignedtoholdallofthecomponentsofalogicalunitinanintegration solution.Forexample,youmightgroupalltheservicesandfilesspecifictoaparticular marketplaceinasinglepackage.Bygroupingthesecomponentsintoasinglepackage, youcaneasilymanipulatethemasaunit.Forexample,youcancopy,reload,distribute, ordeletethesetofcomponents(thepackage)withasingleaction. Althoughyoucangroupservicesusinganypackagestructurethatsuitsyourpurpose, mostsitesorganizetheirpackagesbyfunctionorapplication.Forexample,theymight putallpurchasingrelatedservicesinapackagecalledPurchaseOrderMgtandalltime reportingservicesintoapackagecalledTimeCards. Ontheserver,apackagerepresentsasubdirectorywithinthe IntegrationServer_directory\packagesdirectory.Allthecomponentsthatbelongtoa packageresideinthepackagessubdirectory. Note: EveryelementinwebMethodsDevelopermustbelongtoapackage. ForalistanddescriptionofpackagesinstalledwiththeIntegrationServer,seethe webMethodsIntegrationServerAdministratorsGuide.

Package Management
YoucanusewebMethodsDevelopertoperformcertainpackagemanagementtasks,such ascreating,copying,anddeletingpackages,ontheIntegrationServer.Whenyou performapackagemanagementtask,allofthefilesandservicesinthepackageare affected. Thefollowingtableidentifiesallofthepackagemanagementtasksthatcanbeperformed usingDeveloperortheIntegrationServerAdministrator.Ifyoucanperformthetask withDeveloper,theSeecolumndirectsyoutoapagewithinthisguideforinstructions. FortasksthatcanonlybeperformedusingtheIntegrationServerAdministrator,theSee columndirectsyoutothewebMethodsIntegrationServerAdministratorsGuide. To... Createapackage Activateapackage Copyapackagetoanotherserver See... page 72 webMethodsIntegrationServer AdministratorsGuide page 74

70

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

To... Viewdetailsforapackage Displayspecificpackagesbyfilteringthe PackagesList Documentthepurposeandfunctionofa package Viewthepatchhistoryforapackage

See... page 73 webMethodsIntegrationServer AdministratorsGuide page 76 page 79and webMethodsIntegrationServer AdministratorsGuide page 83 page 77and webMethodsIntegrationServer AdministratorsGuide page 77and webMethodsIntegrationServer AdministratorsGuide page 78and webMethodsIntegrationServer AdministratorsGuide page 81

Assignstartup,shutdown,orreplication servicestoapackage Reloadtheservicesandfilesinapackage intomemorywithoutrestartingtheserver Deletethecontentsofapackage

Assignaversionnumbertoapackage

Identifypackagesthatmustbeloaded beforeaspecificpackageisloaded(package dependencies) Exportapackageorpartialpackage Replicateorcopythecontentsofapackage andsend(publish)ittootherIntegration Servers Disableapackagewithoutdeletingthe package Enableapackagethatyoupreviously disabled Recoverservicesandrelatedfilesfroma deletedpackage Archiveacopyofthepackage(suchasfora backupcopy)

page 78 page 74and webMethodsIntegrationServer AdministratorsGuide webMethodsIntegrationServer AdministratorsGuide webMethodsIntegrationServer AdministratorsGuide webMethodsIntegrationServer AdministratorsGuide webMethodsIntegrationServer AdministratorsGuide

webMethods Developer Users Guide Version 7.1.1

71

3 Working with Packages

Creating a Package
Whenyouwanttocreateanewgroupingforservicesandrelatedfiles,createapackage. Packagescanstoreservices,specifications,ISdocumenttypes,outputtemplates,and schemas. Whenyoucreateapackage,Developercreatesanewsubdirectoryforthepackageinthe filesystemonthemachinewheretheIntegrationServerisinstalled.Forinformation aboutthesubdirectoryanditscontents,seethewebMethodsIntegrationServer AdministratorsGuide.

Guidelines for Naming Packages

Keepthefollowingguidelinesinmindwhennamingnewpackages: Startallpackagenameswithanuppercaseletterandcapitalizethefirstletterof subsequentwords(forexample,PurchaseOrder). Keeppackagenamesshort.Useabbreviationsinsteadoffullnames.Forexample, insteadofProcessPurchaseOrder,useProcessPO. Makesurethepackagenamedescribesthefunctionalityandpurposeoftheservicesit contains. Avoidcreatingpackagenameswithrandomcapitalization(forexample, cOOLPkgTest). Avoidusingarticles(forexample,a,an,andthe)inthepackagename.For example,insteadofTestTheService,useTestService. AvoidusingtheprefixWm.DeveloperusestheWmprefixforpredefined packagesthatcontainservices,ISdocumenttypes,andotherfiles. To create a package 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectPackage,andthenclickNext. DeveloperdisplaystheNewPackagedialogbox. IntheNamefield,typethenameforthenewpackageusinganycombinationofletters, numbers,andtheunderscorecharacter.ClickFinish. DeveloperrefreshestheNavigationpanelanddisplaysthenewpackage. Note: Avoidusingcontrolcharactersandspecialcharacterslikeperiods(.)ina packagename.Thewatt.server.illegalNSCharssettingintheserver.cnffile(which islocatedintheIntegrationServer_directory\configdirectory)definesallthe charactersthatyoucannotusewhennamingpackages.Additionally,the operatingsystemonwhichyouruntheIntegrationServermighthavespecific requirementsthatlimitpackagenames.

72

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

Tip! Youcanquicklycreateapackagebeneaththeserveryouarecurrentlyworking withbyclicking nexttotheNewbuttononthetoolbarandthenclickingPackage. TypethenameofthepackageandthenclickOK. Youcanthencreateafolderbeneaththepackagebyclicking nexttotheNew buttonandthenclickingFolder.Developeraddsthefolderbeneaththepackage,with adefaultnameofUntitled.

Viewing Details for a Package

DoubleclickingapackageintheNavigationpanelexpandsorcollapsesthecontentsof thatpackage.Toviewdetailsforapackageintheeditor,performthestepsinthe followingprocedure. To view details for a package 1 2 Selectthepackageswhosedetailsyouwanttoview. OntheFilemenu,clickOpen.

Formoreinformationaboutpackagedetails,seeAssigningaVersionNumbertoa Packageonpage 78,ViewingthePatchHistoryforaPackageonpage 79,and IdentifyingPackageDependenciesonpage 81.

Optimizing Lock Checking

IftheDevelopersVersionControlSystem(VCS)Integrationfeatureisenabled, Developermightexhibitslowdowns,errormessages(suchasServerversionhas changedandSessionalreadyinuse),andmaystoprespondingcompletelywhenyou expandalargeelement(suchasafolder)oralargepackageintheNavigationpanel.This conditionoccurswhenDeveloperqueriestheIntegrationServertocheckthelockstateof eachelementinapackage.

webMethods Developer Users Guide Version 7.1.1

73

3 Working with Packages

To optimize lock checking 1 2 OpenthefileDeveloper_directory\config\developer.cnfwithatexteditor. Addthefollowingpropertiestothefile:

dev.maxServerLockInfoCalls=<value>

DefinesthemaximumnumberoflockstatequeriesthatwillbemadefromDeveloper toIntegrationServer.Thedefaultvalueis20.Afterthismaximumisreached,cached valuesareretrievedforeachelement.Thesecachedvaluesmaybeinaccurate,butthe onlyresultisthatmenuitemsmaybeenabledordisabledincorrectly.

dev.maxLockInfoCalls=<value>

Definesthemaximumnumberofcachedlockstatesthatareretrieved.Thedefault valueis100.Afterthismaximumisreached,thelastknownlockstateforeach remainingelementisused.Thisstatemaybeincorrect,butasabove,theonlyresultis thatmenuitemsmaybeenabledordisabledincorrectly. Forexample,whenalargepackageisopened(usingthedefaultvalues):Fulllock statusinformationwillberetrievedforthefirst20elements.Forelements21100, cachedlockstateinformationwillberetrieved.Forelements101andabove,thelast knownlockstatewillbeused. 3 4 Savethefile. ShutdownandrestartDeveloper. Note: Thelowerthevaluesforthesesettings,themoretheperformancewillimprove. Applyingavalueofzero(0)tothesesettingswilleliminatealllockstatequeriestothe server.Thismayresultinsometemporarilyoutofsynclockstates,butthesewillbe updatedduringnormalDeveloperoperations. LockstateinformationisupdatedaschildelementsareopenedintheNavigation panel.

Copying a Package to Another Server

YoucancopyapackagetoanotherIntegrationServerinoneoftwoways: From Developer.YoucancopyapackageanditscontentstoanotherIntegrationServer fromwithinDeveloperbyperformingacopyoradraganddropaction.Copying packagesusingeitherofthesemethodsprovidesaquickwaytoshareasetofservices andtheirsupportingfileswithotherdevelopersinadevelopmentenvironment. From Integration Server Administrator.Youcanalsocopyapackagefromwithinthe IntegrationServerAdministratorbyreplicatingthepackage.Youcanthensend,or publish,thepackagetootherIntegrationServers.Copyingpackagesusingthis methodallowsyoutocustomizethewayinwhichpackagesarereplicatedand published.Thismethodisusefulformanagingreleasesbetweendevelopmentand productionenvironments,fordeployingreleasestopartnersorcustomers,orfor

74

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

distributingpackageupdatestodevelopersworkinginlarge,collaborative environments. Forinformationaboutreplicatingpackagesandmanagingreleasesfromwithin IntegrationServerAdministrator,seethewebMethodsIntegrationServerAdministrators Guide. Whencopyingpackages,keepthefollowingpointsinmind. Youcancopyapackagetoadifferentserveronlyifyouareamemberofagroup assignedtotheReplicatorsACLonthesourceanddestinationserversandyouare loggedontobothservers. Beforeyoucopyapackagethatcontainselementswithunsavedchanges,youmust savethechanges. YoucannotundoacopyactionusingtheEditUndocommand. Youcannotcopyapackagetoanotherserverifthedestinationserveralreadycontains apackagewiththatname. Note: BecauseUNIXdirectoriesarecasesensitive,IntegrationServersrunningina UNIXenvironmentwillallowpackageswithsimilarnamestoresideonthesame server.Forexample,youcancopyapackagenamedorderProcessingtoaserverthat containsapackagenamedOrderProcessing. Ifyoucopyapackagethatdependsonotherpackagestoload(thatis,contains packagedependencies),andtherequiredpackagesarenotpresentonthedestination server,thepackagewillbecopiedbutitwillnotbeenabled. Formoreinformationaboutsettingpackagedependencies,seeIdentifyingPackage Dependenciesonpage 81. Formoreinformationaboutcopyingelementswithinapackage,seeChapter 2, ManagingElementsintheNavigationPanel. To copy a package 1 2 3 Selectthepackagethatyouwanttocopy. OntheEditmenu,clickCopy. Ifthepackageyouwanttocopycontainselementswithunsavedchanges,Developer alertsyouthatthepackagecannotbecopieduntilyousavethechanges.ClickOKto closethealertdialogbox.Then,savethechangesandrepeatthecopyaction. Selecttheserverwhereyouwanttocopythepackage. OntheEditmenu,clickPaste After. Tip! Youcanalsocopypackagesbyclickingthemanddraggingthemtotheirnew location.Developerretainsacopyofthepackageanditscontentsonthesource server.

4 5

webMethods Developer Users Guide Version 7.1.1

75

3 Working with Packages

Documenting a Package
Youcancommunicatethepurposeandfunctionofapackageanditsservicestoother developersbydocumentingthepackage. To create documentation for a package 1 DocumentthepackageinoneormoreWebdocuments(suchasHTMLpages).Be suretonamethehomepageforthepackagedocumentationindex.html.The index.htmlfilecancontainlinkstotheotherWebdocumentsforthepackage.An index.htmlfileexistsforeachpackageinstalledbytheIntegrationServer. PlacethedocumentsinthepubsubdirectoryforthepackageontheIntegration Server. Forexample,placethepackagedocumentationforapackagenamed PurchaseOrdersinthefollowingdirectory: IntegrationServer_directory\packages\PurchaseOrders\pub Tip! Analternatelocationforpackagedocumentationisthe IntegrationServer_directory\packages\docdirectory.Typically,thisdirectoryis usedforreferencematerialsuchasPDFsthatdonotneedtobepublishedtothe Web. To access documentation for a package EntertheURLforthepackagedocumentation.TheURLsforpackagedocumentation havethefollowingformat: http://serverName:port/PackageName/DocumentName where: serverName:port PackageName DocumentName isthenameandportaddressoftheIntegrationServeronwhich thepackageresides. isthenameofthepackageforwhichyouwantdocumentation. isthenameoftheWebdocumentyouwanttoaccess.Ifyoudo notspecifyaDocumentName,theIntegrationServer automaticallydisplaystheindex.htmlfile.

76

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

Reloading a Package
Sometimes,youneedtoreloadapackageontheservertoactivatechangesthathavebeen madetoitoutsideofDeveloper.Youneedtoreloadapackageifanyofthefollowing occurs: AJavaservicethatwascompiledusingjcodeisaddedtothepackage. Newjarfilesareaddedtothepackage. Anyoftheconfigurationfilesforthepackagearemodified. Note: ReloadingapackageisnotthesameasrefreshingtheNavigationpanel.When yourefreshtheNavigationpanel,webMethodsDeveloperretrievesafreshcopyof thecontentsofallthepackagesfromthememorytheIntegrationServer.Whenyou reloadapackage,theIntegrationServerremovestheexistingpackageinformation frommemoryandloadsnewversionsofthepackageanditscontentsintoits memory. To reload a package 1 2 IntheNavigationpanel,selectthepackageyouwanttoreload. OntheFilemenu,clickReload Package.

Deleting a Package
Whenyounolongerneedtheservicesandfilesinapackage,youcandeletethepackage. DeletingapackageremovesthepackageandallofitscontentsfromtheNavigation panel. WhenyoudeleteapackagefromDeveloper,theIntegrationServersavesacopyofthe package.Ifyoulaterwanttorecoverthepackageanditscontents,contactyourserver administrator.OnlyIntegrationServerAdministratoruserscanrecoverapackage.For moreinformationaboutrecoveringpackages,seethewebMethodsIntegrationServer AdministratorsGuide. Beforeyoudeleteapackage,makesurethat: Otherusersorotherservicesdonotuse(dependon)theservices,templates,IS documenttypes,andschemasinthepackage.YoucanusetheFind Dependents commandtoidentifyotherservicesthataredependentonaserviceinapackagethat youwanttodelete.Formoreinformation,seeFindingDependentsandReferences onpage 60. Allelementsinthepackagethatyouwanttodeleteareunlocked,orlockedbyyou.If thepackagecontainselementsthatarelockedbyothersorsystemlocked,youcannot deletethepackage.

webMethods Developer Users Guide Version 7.1.1

77

3 Working with Packages

To delete a package 1 2 IntheNavigationpanel,selectthepackageyouwanttodelete. OntheEditmenu,clickDelete.

Exporting a Package or Element

Packagesorpartsofapackage,suchasafolder,canbeexportedtoyourharddriveso thattheycanbesharedwithpartnersordevelopers.Youcaninstallanexportedpackage onanotherserverbyusingthepackagepublishingfunctionalityintheIntegrationServer Administrator.Lockinginformationisnotexported. To export a package 1 2 3 IntheNavigationpanel,selectthepackageyouwanttoexport. OntheFilemenu,clickExport.DeveloperdisplaystheExportTodialogbox. Selectthelocationonyourharddrivewhereyouwanttheexportedpackagetoreside. ClickSave. ThisexportsthepackagetoaZIPfileandsavesitonyourharddrive.TheZIPfilecan thenbepublishedonanotherserver. To export an element 1 2 3 IntheNavigationpanel,selectthefolderorelementthatyouwanttoexport. OntheFilemenu,clickExport.DeveloperdisplaystheExportTodialogbox. Selectthelocationonyourharddrivewhereyouwanttheexportedpartialpackageto reside.ClickSave. ThisexportsthefolderorelementtoaZIPfileandsavesitonyourharddrive.The ZIPfilecanthenbeunzippedintothensdirectoryofapackageontheserver.

Assigning a Version Number to a Package

Youcanassignaversionnumbertoapackagetoidentifydifferentversionsofthe package.Forexample,youmightwanttoassignanewversionnumbertoapackage whenyouaddnewservicestothepackageorafteryoufixbugsinapackage.Youmight findassigningversionnumbersespeciallyhelpfulifyouworkinadevelopment environmentwheremorethanonepersonmakeschangestoapackage. Bydefault,Developerassignstheversionnumber1.0toeachpackagethatyoucreate.

78

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

Important! Whenyouchangetheversionnumberofapackage,makesurethatyou updatethepackagedependenciesforotherpackagesthatdependontheearlier versionofthispackage. Tip! AssignandchangepackageversionnumbersthroughDeveloperonlywhenthe packagesareinadevelopmentstage.Toavoiddifficultiesinstallingpackagereleases, donotchangeversionnumbersonpackagesyoureceivefromtradingpartners, packagestowhichyousubscribe,orpackagesinstalledwiththeIntegrationServer. To assign a version number to a package 1 2 3 4 IntheNavigationpanel,selectthepackagetowhichyouwanttoassignaversion number. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesSettingstab. InthePackage Versionfield,typetheversionnumberyouwanttoassigntothe package.Besuretoformattheversionnumberinoneofthefollowingways:X.Xor X.X.X(forexample,1.0,2.1, 2.1.3,or3.1.2). OntheFilemenu,clickSavetosaveyourchanges. Iftheversionnumberyouentereddoesnotuseoneoftheformatsspecifiedinstep 4, Developerdisplaysamessagestatingthattheformatisnotcorrect. Note: YoucanalsousetheIntegrationServerAdministratortoassignversionnumbers topackages.Formoreinformation,seethewebMethodsIntegrationServer AdministratorsGuide.

Viewing the Patch History for a Package

Foreachpackage,Developertracksanddisplaysthehistoryofinstalledpatches.Apatch isapartialupgrade,change,orfixtothecontentsofapackage. Youmightwanttocheckapackagespatchhistoryforthefollowingreasons: Toavoidoverwritingtheinstalledpackagewithalowerversionofthesamepackage. Toviewthechangesthatareincludedineachversionofthepackage. ToinformSoftware AGCustomerCarewhichversionsofpredefinedpackagesare installedonyourIntegrationServer. Whenyouopenapackageintheeditor,thepackagesSettingstabdisplaysthepatch historysincethelastfullreleaseofthepackage.(Afullreleaseofapackageincorporates allpreviouspatchesforthepackage.)

webMethods Developer Users Guide Version 7.1.1

79

3 Working with Packages

The Settings tab displays patch history for the package

These fields display information about the currently installed patch...

...and these fields track the patch history for the package.

Note: WiththeexceptionofthePackage versionfieldandthefieldsunderPackage dependencies,thefieldsontheSettingstabaredisplayonly. Note: Whentheserveradministratorinstallsafullreleaseofapackage(areleasethat includesallpreviouspatchesforthepackage),theIntegrationServerremovesthe existingpatchhistory.Thishelpstheserveradministratoravoidpotentialconfusion aboutversionnumbersandreestablishabaselineforpackageversionnumbers. To view patch history for a package 1 2 3 IntheNavigationpanel,selectthepackageforwhichyouwanttoviewapatch history. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesSettingstabandreviewthefieldsunderPatch history. This field... Name Version Specifies... Thenameofthepackage. Theversionnumberofthepackage.Auserassignsaversion numberwhentheycreateapackagerelease.Bydefault,Developer assignsversion1.0toanewpackage.

80

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

This field... Build

Specifies... Thebuildnumberofthepackage.Thebuildnumberisageneration numberthatauserassignstoapackageeachtimethepackageis released.Forexample,ausermightreleaseversion1.0ofthe Financepackagetentimesandassignbuildnumbers1,2,310to thedifferentreleasesorbuildsofthepackage. TheBuildnumberisnotthesameastheVersionnumber.One versionofapackagemighthavemultiplebuilds.

Description Time JVM Number Publisher Patch Number

Abriefdescriptionofthepackagewrittenbytheuserwhocreated thepackagerelease. Thetimeatwhichthepackagerelease(patch)wascreated. TheversionoftheJVM(Javavirtualmachine)requiredtorunthe package. Thenameofthepublishingserverthatcreatedthepackagerelease. Thepatchnumbersincludedinthisreleaseofthepackage.

Identifying Package Dependencies

Ifapackageneedstheservicesinanotherpackagetoloadbeforeitcanload,youmustset uppackagedependencies.Forexample,youshouldidentifypackagedependenciesifa startupserviceforapackageinvokesaserviceinanotherpackage.Thestartupservice cannotexecuteifthepackagecontainingtheinvokedservicehasnotyetloaded. YoushouldalsoidentifypackagedependenciesifJavaservicesinapackageneedto accessJavaclassescontainedinanotherpackage. Whenyouidentifyapackagedependency,youmustindicatetheversionnumberofthe packagethatneedstoloadfirst.Forexample,theFinancepackagemightdependon version2.0oftheFinanceUtilpackage.Itispossiblethattheservicesandelements neededbyadependentpackagearecontainedinmorethanoneversionofthesame package.Forexample,theFinancepackagemightdependonversion2.0orlaterofthe FinanceUtilpackage. Important! Ifyoucreatenewadapterservicesandadapternotifications,youshould savetheminpackagesthatidentifythewebMethodsAdapterNamepackageasa packagedependency.

webMethods Developer Users Guide Version 7.1.1

81

3 Working with Packages

Important! OtherwebMethodscomponentsmightincludepackagesthatregisternew typesofelementsinDeveloper.Youshouldsaveinstancesofthesenewelementtypes inpackagesthatlisttheregisteringpackageasapackagedependency.Theregistering packageneedstoloadbeforeyourpackagessothatDevelopercanrecognize instancesofthenewelementtype.Forexample,ifyoucreatenewflatfileschemas, youshouldsavetheflatfileschemasinpackagesthatidentifytheWmFlatFile packageasapackagedependency. To identify package dependencies for a package 1 2 3 4 5 IntheNavigationpanel,selectthepackageforwhichyouwanttospecifypackage dependencies. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesSettingstab. UnderPackage Dependencies,click .

IntheEnterInputValuesdialogbox,enterthefollowinginformation: In this field... Package Version Specify... ThenameofthepackageyouwantIntegrationServertoloadbefore thepackageselectedintheNavigationpanel. TheversionnumberyouwantIntegrationServertoloadbeforethe packageselectedintheNavigationpanel. Morethanoneversionofthesamepackagemightcontainthe servicesandelementsthatadependentpackageneedsthe IntegrationServertoloadfirst.Youcanuseanasterisk(*)asa wildcardintheversionnumbertoindicatethatanyversionnumber greaterthanorequaltothespecifiedversionwillsatisfythepackage dependency.Forexample,tospecifyversion3.0orlaterofa package,type3.*fortheversionnumber.Tospecifyversions3.1or later,type3.1.*fortheversionnumber. Ifanyversionofthepackagesatisfiesthepackagedependency,type
*.*astheversionnumber.

6 7

ClickOK. OntheFilemenu,clickSave. Important! Onlyoneversionofapackagecanbeinstalledatonetime.Iftheavailable versionofthepackagespecifiedinthepackagedependencyisnotthecorrectversion, theIntegrationServerdoesnotloadthedependentpackage.TheIntegrationServer writesadependencyloaderrorforthedependentpackagetotheserverlog.

82

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

Important! Makesurethatyoudonotcreatecircularpackagedependencies.For example,ifyouidentifyFinanceUtilasadependentpackagefortheFinance package,donotidentifyFinanceasadependentpackagefortheFinanceUtil package.Ifyoucreatecircularpackagedependencies,neitherpackagewillloadthe nexttimeyoustarttheIntegrationServer.

Removing Package Dependencies

Usethefollowingproceduretoremoveapackagedependencythatisnolongerneeded. Forexample,tocontinuetheexamplefrompage 81,ifyoudeletetheserviceinFinance thatinvokestheserviceinFinanceUtil,thenyouwouldnolongerneedapackage dependencyontheFinanceUtilpackage.Anothercasewhereyouwouldremovethe packagedependencyisifyoumovetheservicesintheFinanceUtilpackageintothe Financepackage. To remove a package dependency 1 2 3 4 5 6 IntheNavigationpanel,selectthepackageforwhichyouwanttoremoveapackage dependency. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesSettingstab. UnderPackage Dependencies,selectthepackagedependencyyouwanttoremove. Click .

OntheFilemenu,clickSave.

Assigning Startup, Shutdown, and Replication Services

YoucansetupservicestoautomaticallyexecuteeachtimeIntegrationServerloads, unloads,orreplicatesapackage.Thesetypesofservicesarecalledstartup,shutdown,or replicationservices.

What Is a Startup Service?

AstartupserviceisonethatIntegrationServerautomaticallyexecuteswhenitloadsa packageintomemory.Theserverloadsapackage: Atserverinitialization(ifthepackageisenabled). WhensomeoneusesDeveloperortheIntegrationServerAdministratortoreloada package. WhensomeoneusesDeveloperortheIntegrationServerAdministratortoenablea package.

webMethods Developer Users Guide Version 7.1.1

83

3 Working with Packages

Startupservicesareusefulforgeneratinginitializationfilesorassessingandpreparing (forexample,settinguporcleaningup)theenvironmentbeforetheserverloadsa package.However,youcanuseastartupserviceforanypurpose. Tip! Ifastartupserviceinvokesaserviceinanotherpackage,makesuretoidentifythe otherpackageasapackagedependencyforthepackagecontainingthestartup service.

What Is a Shutdown Service?

AshutdownserviceisonethattheIntegrationServerautomaticallyexecuteswhenit unloadsapackagefrommemory.Theserverunloadsapackagefrommemory: Atservershutdownorrestart. WhensomeoneusestheIntegrationServerAdministratortodisablethepackage. WhensomeoneusestheIntegrationServerAdministratortoreloadapackagebefore itisremovedfrommemory. Shutdownservicesareusefulforexecutingcleanuptaskssuchasclosingfilesand purgingtemporarydata.Youcouldalsousethemtocaptureworkinprogressorstate informationbeforeapackageunloads.

What Is a Replication Service?

AreplicationserviceisonethatIntegrationServerautomaticallyexecuteswhenit preparestoreplicateapackage.AreplicationserviceexecuteswhentheIntegration ServerAdministratorcreatesapackagerelease(fullreleaseorpatch)orcreatesapackage archive. Replicationservicesprovideawayforapackagetopersiststateorconfiguration informationsothattheseareavailablewhenthepublishedpackageisactivatedonthe remoteserver. Note: Thetermreplicationservicedoesnotrefertotheservicescontainedin pub.replicatorortoservicesthatsubscribetoreplicationevents(replicationevent services).

84

webMethods Developer Users Guide Version 7.1.1

3 Working with Packages

Guidelines for Assigning Startup, Shutdown, and Replication Services

Keepthefollowingguidelinesinmindwhenassigningstartup,shutdown,and replicationservicestopackages: Whenyouassignastartuporshutdownservicetoapackage,youcanonlyassigna servicethatresidesinthesamepackage.Forexample,astartupserviceforthe FinancepackagemustbelocatedintheFinancepackage. Whenyouassignareplicationservicetoapackage,youcanassignanyservicefrom anyloadedpackageonIntegrationServer,includingthecurrentpackage. Becauseservicesinapackagearenotmadeavailabletoclientsuntilthepackages startupservicesfinishexecuting,youshouldavoidimplementingstartupservices thataccessbusyremoteservers.Theywilldelaytheavailabilityofotherservicesin thatpackage. Youcanassignoneormorestartupservicestoapackage;however,youcannot specifytheorderinwhichtheservicesexecute.Ifyouhaveaseriesofstartupservices thatneedtoexecuteinaspecificorder,createawrapperservicethatinvokesallthe startupservicesinthecorrectorder.Designatethewrapperserviceasthestartup serviceforthepackage.

Assigning Startup, Shutdown, and Replication Services

Usethefollowingproceduretoidentifystartup,shutdown,andreplicationservices. To assign startup, shutdown, and replication services 1 2 3 4 IntheNavigationpanel,selectthepackagetowhichyouwanttoassignstartup, shutdown,orreplicationservices. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesStartup/Shutdown/Replication Servicestab. Toassignastartupservice,underStartup services,selecttheservicefromtheAvailable Serviceslist,andclick . Repeatthisstepforeachserviceyouwanttoaddasastartupserviceforthepackage. Note: AservicethatyoujustcreateddoesnotappearintheAvailable Serviceslistif youhavenotrefreshedyoursessionontheserversinceyoucreatedtheservice. 5 Toaddashutdownservice,under Shutdown services,selecttheservicefromthe Available Serviceslist,andclick . Repeatthisstepforeachserviceyouwanttoaddasashutdownserviceforthe package.

webMethods Developer Users Guide Version 7.1.1

85

3 Working with Packages

Toaddareplicationservice,dothefollowing: a b UnderReplication Services,click .

IntheEnterInputValuesdialogbox,intheServicefield,dooneofthefollowing:

Typetheservicenameintheformat:folderName:serviceName Click tonavigatetoandselecttheservicethatyouwanttouseasa replicationservice.

c d

ClickOK. Repeatthesestepsforeachserviceyouwanttoaddasareplicationservice.

Removing Startup, Shutdown, and Replication Services

Youmightneedtoremoveastartup,shutdown,orreplicationserviceiftheserviceisno longerneeded,hasbeendeleted,orhasbeenincorporatedintoanotherservice(suchasa wrapperservice). Tip! Ifyouremoveastartupservicethatinvokedaserviceinanotherpackageandthe packagewasidentifiedasapackagedependency,makesureyouremovethepackage dependencyafteryouremovethestartupservice. To remove startup, shutdown, and replication services 1 2 3 4 IntheNavigationpanel,selectthepackageforwhichyouwanttoremovestartup, shutdown,orreplicationservices. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesStartup/Shutdown/Replication Servicestab. Dooneormoreofthefollowing:

Toremoveastartupservice,underStartup services,selecttheserviceyouwantto removefrom Selected serviceslist,andclick . . Toremoveashutdownservice,underShutdown services,selecttheserviceyou wanttoremovefromtheSelected serviceslist,andclick Toremoveareplicationservice,underReplication services,selectthereplication serviceyouwanttoremoveandclick .

86

webMethods Developer Users Guide Version 7.1.1

Locking and Unlocking Elements

88 90 94 99 101

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

87

4 Locking and Unlocking Elements

Basic Concepts
InwebMethodsDeveloper,youcanmanagechangestoelementsduringdevelopmentby lockingthem.Thispreventstwodifferentusersfromeditinganelementatthesametime. Youcanlockelementssuchasflowservices,Javaservices,schemas,andspecifications. AllelementsinDevelopersNavigationpanelarereadonlyuntilyoulockthem.Youcan editanelementonlyifyouownthelockontheelement.However,youcanuseandruna serviceregardlessofitslockstatus,aslongasyouhaveExecuteaccesstotheservice.For details,seeChapter 5,AssigningandManagingPermissions. ThischapterdescribeslocallockingontheIntegrationServer,whichisthedefault lockingmodeofDeveloper.IfyouenableDevelopersVCSIntegrationfeature,elements arelockedandunlockedwhenyoucheckthemoutoforintoyourversioncontrolsystem repository.FormoreinformationaboutimplementingandusingtheVCSIntegration feature,seethewebMethodsVersionControlSystemIntegrationDevelopersGuideinthe webMethods_directory\_documentationdirectory.

What Is a Lock?
Alockonanelementpreventsanotheruserfromeditingthatelement.Therearetwo typesoflocks:userlocksandsystemlocks.Whenanelementislockedbyyou,youhavea userlock.TheelementisreadonlytoallotherusersontheIntegrationServer.Another usercannotedittheelementuntilyouunlockit. Whenanelementssupportingfiles(node.xml,forexample)aremarkedreadonlyonthe IntegrationServer,theelementissystemlocked.Forexample,theserveradministratorhas theabilitytomarkanelementssupportingfilesontheserverasreadonly,inwhichcase theyaresystemlocked.Toedittheelement,youmustasktheserveradministratorto removethesystemlock(thatis,maketheelementsfileswritable),andthenyoumust reloadthepackageinwhichtheelementresides. Important! WhenanIntegrationServerhastheVCSIntegrationfeatureenabled, systemlockingiseffectivelydisabledforelementsthatarecheckedintotheversion controlsystem.TheVCSIntegrationfeaturewilloverrideanyread/writestatus changesappliedmanuallybyaserveradministrator. ElementsareshowninthefollowingwaysinDeveloper: Element Status Notlocked Lockedbyyou Can I edit? No Yes How do I gain rights to edit? ClickFileLock for Edit. N/A

88

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

Element

Status Lockedbyanotheruser Lockedbythesystem

Can I edit? No No

How do I gain rights to edit? Contacttheusertounlock. Contacttheserver administratortounlock.

How Do I Know Who Has an Element Locked?

OneveryelementintheNavigationpanel,youcanviewthelockstatusbyusingtheLock Statuscommand.Thiscommandprovidesinformationabouttheelementsuchasthe usernameofthepersonwhoownsthelockandwhentheylockedit.Ifanelementis systemlocked,youcanalsousetheLock Statuscommandtoobtainthenamesofthe serverfilesthatarereadonlyontheserver.Fordetails,seeViewingtheStatusofLocked Elementsonpage 92andViewinganElementsCorrespondingServerFileson page 98.

When Do I Lock an Element?

Youlockanelementwhenyouwanttomakechangestotheelement.Fordetails,see LockingElementsonpage 90.

When Do I Unlock an Element?

Youunlockanelementaftermakingyourchangesandsavingthosechangestotheserver. Itisimportanttounlocktheelementsyouaredonewithsothatotherusersontheserver canaccessthem.Fordetails,seeUnlockingElementsonpage 94. Ifyouwanttoautomaticallyunlockanelementaftersavingit,youcanenableasettingon theOptionsdialogbox.Fordetails,seeAutomaticallyUnlockingElementsAfter Savingonpage 98.

webMethods Developer Users Guide Version 7.1.1

89

4 Locking and Unlocking Elements

Locking Elements
Beforeyoueditanelement,youmustlockit.Thisensuresthatyouaretheonlyperson workingonaparticularelementatatime,preventingthelossofchanges.Elementscan onlybelockedbyoneuseratatime.Iftheelementyouneedisalreadylocked,request thatthecurrentownerofthelockreleaseit.Iftheelementissystemlocked,requestthat theserveradministratorreleaseitbymakingthecorrespondingserverfileswritable.

Locking Elements
ElementsarelockedbywebMethodsusername(thenameyouusetologontothe IntegrationServer).Becauseofthis,itisimportantthatyouuseadistinctusernametolog ontotheserver.Ifyouchangeusernames,youwillbeunabletoeditorunlockitemsthat youlockedusingyouroldusername. Whenlockingelements,keepthefollowingpointsinmind: Whenyoucreateanewelement,itislockedautomaticallyforyou. Inordertolockanelement,youmusthaveWriteaccessrightstoit.Fordetails,see Chapter 5,AssigningandManagingPermissions. Whenyoulockanelement,Developerobtainsandlocksthelatestversionofthe elementthathasbeensavedonthewebMethodsIntegrationServer. Elementsgeneratedbyaservice(includinganadapterservice)arenotlocked automatically. Whenyouselectmultipleelementstolock,someelementsintheselectionmaynotbe availabletolockbecausetheymaybesystemlocked,lockedbyanotheruser, elementstowhichyoudonothaveWriteaccess,orelementsthatcannotdirectlybe locked.Developerwillnotifyyouthattheseelementscannotbelockedandwilllock therest. Whenyoulockanadapternotification,Developeralsolocksitsassociated publishabledocumenttype.Youcannotdirectlylockthepublishabledocumenttype associatedwithanadapternotification. Whenyoulockafolderorpackage,youonlylockexisting,unlockedelementswithin it.Otheruserscanstillcreatenewelementsinthatfolderorpackage. Note: UserscannotcreateJavaandC/C++servicesinafolderorpackagewhile otherusersownthelockonthefolderorpackage.Thesetypesofservicesrequire thatallexistingJavaandC/C++servicesinthefolderareunlockedandtheuser hasWriteaccesstoallJavaandC/C++servicesinthefolder.Fordetails,see LockingJavaandC/C++Servicesonpage 91.

90

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

WhenyoulockaJavaorC/C++service,DeveloperlocksallotherJavaorC/C++ serviceswithinthefolder.Fordetails,seeLockingJavaandC/C++Serviceson page 91. Youcannotlockalistenerorconnectionelement. To lock elements 1 2 IntheNavigationpanel,selecttheelementsthatyouwanttolock. OntheFilemenu,clickLock for Edit. Iftheelementsweresuccessfullylocked,agreencheckmarkappearsnexttotheir iconsintheNavigationpanel.Ifoneormoreoftheelementscouldnotbelocked(for example,iftheyaresystemlocked,lockedbyanotheruser,orelementstowhichyou donothaveWriteaccess),Developerdisplaysadialogboxlistingthem.For informationabouttroubleshootinglockproblems,seeLock/UnlockProblemson page 99. Tip! Youcanalsolockanelementthatisopenintheeditorbyrightclickingthe elementstabortitlebarandthenclickingLock for Edit.

Locking Java and C/C++ Services

WhenyoulockJavaandC/C++services,therearespecialconsiderationstokeepinmind. Locking and unlocking actions on Java and C/C++ services are folder-wide.AllJavaand C/C++servicesinafoldersharethesame.javaand.classfilesontheIntegration Server.Thesefiles,locatedinthe\codesubdirectoryofapackage,correspondtoall services(exceptflowservices)inafolder.Therefore,whenyoulockaJava/Cservice, allJava/Cservicesinthatfolderarelocked. Forexample,ifyoulockaJavaserviceinafolderA,allJavaandC/C++servicesin folderAarelockedbyyou.Similarly,ifanotheruserhaslockedaJavaservicein folderB,youcannotadd,edit,move,ordeleteanyJavaorC/C++servicesinfolderB. Locking actions on Java and C/C++ services are ACL dependent.Ifyouwanttolockoneor moreJavaorC/C++serviceswithinafolder,youmusthaveWriteaccesstoallJava andC/C++servicesinthatfolder.ThisisbecauseJavaandC/C++serviceswithina foldersharethesame.javaand.classfiles. The jcode development environment operates independently of locking.Ifyouusejcodeto developJavaservices,youdonothavethelockingfunctionalitythatisavailablein theIntegrationServer.Whenyouusejcode,youmaycompileaservicethatislocked byanotheruser,overwritingthatuserschangestotheservice.Therefore,ifyouuse jcode,donotusethelockingfeaturesintheIntegrationServer.

webMethods Developer Users Guide Version 7.1.1

91

4 Locking and Unlocking Elements

Before you save a Java or C/C++ service, multiple corresponding files must be writable on the server. AsingleJavaorC/C++servicecorrespondstothefollowingfiles:
.java .class .ndf .frag(maynotbepresent)

BeforeyousaveaJavaorC/C++service,alloftheprecedingfilesmustbewritable. Therefore,makesurethatallsystemlocksareremovedfromthosefilesbeforesaving.

Locking Templates
AtemplatecanbeusedwithoneormoreservicesontheIntegrationServer.Currently, youcannotlockatemplateasanentity,onlytheservicetowhichitisattached.Following areconsiderationsforworkingwithtemplatesinacooperativedevelopment environment. To create or edit a template for a service,youmusthavetheservicelocked. The template for a service can change without your knowledge.Sinceatemplatecanbe attachedtooneormoreservices,keepinmindthatasharedtemplatecanchange withoutyourknowledge.Forexample,ifyourtemplateisattachedtoaservicethat anotheruserlocksandedits,thatusercanchangeyourtemplate.

System Locking Elements

Ifyouareaserveradministrator,youcansystemlockanelementbyusingtheserversfile systemtomaketheelementssupportingserverfilesreadonly.Ifyoudonotknowthe namesofthefilesthatcorrespondtoaparticularelement,usetheLock Statuscommand. Fordetails,seeViewinganElementsCorrespondingServerFilesonpage 98.Usually,a systemlockisnotreflectedinwebMethodsDeveloperortheIntegrationServer Administratoruntilyoureloadthepackageinwhichtheelementresides. Important! Beforeyousystemlockanelement,alwaysverifythatitisnotlockedbya userontheIntegrationServer.Ifanelementbecomessystemlockedwhileauseris editingit,theuserwillnotknowuntilheorshetriestosavechangestotheelement.If thisoccurs,maketheelementscorrespondingfileswritableontheserver.Afterthisis done,theusercansavehisorherchangestotheelement.

Viewing the Status of Locked Elements

Thelockstatusofanelementtellsyouifanelementisavailableforlocking,andifnot, whoownsthelockandwhentheylockedit.Youcanviewthestatusofalockedelement toseewhoownsthelockoryoucanviewalistofallelementsforwhichyouownthe lock.

92

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

Whenviewinganelementslockstatus,keepthefollowingpointsinmind: Iftheelementhasbeensystemlockedsinceyoulastreloadedthepackage,Developer willnotshowthesystemlockstatusintheLockingStatusdialogboxuntilyoureload thepackage. Whenanotheruserunlocksanelement,youmustrefreshtheNavigationpanelto reflecttheupdatedstatus.Similarly,whentheserveradministratorremovesasystem lockfromanelement,youmustreloadthepackageinwhichtheelementresidesto reflecttheupdatedstatus. To view lock status for an element 1 2 IntheNavigationpanel,selecttheelementforwhichyouwanttoviewthestatus. OntheFile menu,clickLock Status.Thefollowingdialogboxappearsiftheelementis lockedbysomeoneelse.Asimilardialogappearsiftheelementissystemlockedor lockedbyyou. Locking Status dialog box

To list all elements locked by you OntheTools menu,clickMy Locked Elements.TheMyLockedElementsdialogbox appears. My Locked Elements dialog box

webMethods Developer Users Guide Version 7.1.1

93

4 Locking and Unlocking Elements

YoucanunlockindividualelementsfromthisdialogboxbypressingtheCTRLkeyas youclickeachelementandthenclickingUnlock.Youcanunlockallelementsbyclicking Unlock All.Formoreinformationaboutunlockingelements,seeUnlockingElementson page 94.

Copying, Moving, or Deleting Locked Elements

Youcancopyalockedelementtoanotherfolderorpackage.However,youcannotmove, rename,ordeleteanelementunlessitislockedbyyouorunlocked.

Unlocking Elements
Afteryoueditanelementandsavechangestotheserver,youshouldunlockittomakeit availabletootherusers.Thereareseveralwaystounlockelements,dependingon whetheryouareamemberoftheDevelopersACLortheAdministratorsACL.Ifyouare adeveloper,youcanunlockelementsinDeveloper.Ifyouareanadministrator,youcan unlockelementsintheIntegrationServerAdministratoraswellasinDeveloper.

Unlocking Elements Using Developer

Youmustexplicitlyunlockelements.Disconnectingfromtheserverdoesnotunlockyour element(s),sinceyourlocksaremaintainedfromsessiontosession. Whenunlockingelements,keepthefollowingpointsinmind: WhenyouunlockasingleJavaorCservice,DeveloperunlocksallotherJavaorC serviceswithinthefolder.Fordetails,seeLockingJavaandC/C++Serviceson page 91. IfaJavaorCserviceinafolderhasunsavedchanges,youwillnotbeabletounlock otherJavaorCserviceswithinthatfolder.Savethechangesandthenunlockthe services. Whenyouunlockanadapternotification,Developeralsounlocksitsassociated publishabledocumenttype.Youcannotdirectlyunlockthepublishabledocument typeassociatedwithanadapternotification. Youcannotunlockalistenerorconnectionelement.

94

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

To unlock elements using Developer 1 IntheNavigationpanel,selecttheelementsthatyouwanttounlock. Note: Besuretosavechangestotheelementsbeforeyouattempttounlockthem. 2 3 OntheFilemenu,clickUnlock. Iftheelementsyouwanttounlockcontainunsavedchanges,Developeralertsyou thattheelementscannotbeunlockeduntilyousavethechanges.ClickOKtoclosethe alertdialogbox.Then,savethechangesandrepeattheunlockaction. Ifoneoftheelementsyouselectedtounlockisapublishabledocumenttype associatedwithanadapternotification,andyoudidnotalsoselecttheadapter notification,Developeralertsyouthattheelementscannotbeunlocked.ClickOKto closethealertdialogbox.Then,reselecttheelements(includingtheappropriate adapternotifications)andrepeattheunlockaction.

TheNavigationpanelrefreshesandthegreencheckmarknexttotheelementdisappears. Tip! Youcanalsounlockelementsusingthefollowingtechniques: Tounlockanelementthatisopenintheeditor,rightclicktheelementstabortitle barandthenclickUnlock. Tounlockallelementstowhichyouownthelock,usetheToolsMy Locked Elementscommand.

Unlocking an Element Using the Integration Server Administrator

Important! Becautiouswhenyouremoveuserlockstopreventauserfromlosing changes.Ifyouunlockanelementwhileauseriseditingit,theuserwillnotknow untilheorshetriestosavechangestotheelementandtheactionfails.Always confirmwiththeuserbeforeremovinghisorherlockonanelement. To unlock an element using the Integration Server Administrator 1 2 IntheIntegrationServerAdministrator,underPackages,clickManagement. ClickView Locked Elements.Thefollowingscreenappears,showingallelementsthat haveuserlocksandsystemlocks.

webMethods Developer Users Guide Version 7.1.1

95

4 Locking and Unlocking Elements

Locked Elements screen

localhost means the machine on which the server is running

ClickUnlock Elements.Thefollowingscreenappears. Unlock Selected Elements screen

Locked by System. Listselementswhosecorrespondingfilesaremarkedreadonly ontheserverfilesystem.YoucannotremoveasystemlockviatheServer Administrator.Ontheserversfilesystem,youmustmaketheelementsfiles writableandreloadthepackage.Fordetails,seeUnlockingaSystemLocked Elementonpage 97. Locked by Current User. Listselementsthatarelockedbyyou,theserver administrator(ortheusernamewithwhichyouloggedontotheIntegration ServerAdministrator).Beforeyouunlockanitem,makesurethatyouhavesaved allchangestotheserver. Locked by Other Users. Listselementsthatarelockedbyotherusersontheserver. Beforeyouremoveauserslock,makesurethattheuserhassavedallchangesto theserver.Ifnot,theuserwillloseallchangesthattheymadetotheelementsince theylastsavedittotheserver.

96

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

Selecttheelementsthatyouwanttounlock(afterinformingusersifnecessary)and clickUnlock Selected Elements. DevelopersusingwebMethodsDevelopershouldrefreshtheirNavigationpanelto updatetheirviewofthelockstatusofallelements. Important! Ifyoureceiveafailedtounlockmessage,itmeansthattheserverfilesfor alockedelementweredeletedfromtheserver.UsetheSync to Name Spacecommand toupdatetheIntegrationServerAdministratorsviewoflockedelements.

Unlocking a System Locked Element

Ifyouareaserveradministrator,youcanremoveasystemlockfromanelementusing theserversfilesystem.Afteryouremovethesystemlock,youmustreloadthepackage inwhichtheelementresidestoreflecttheelementsupdatedstatus.IfyouuseDeveloper, youmustrefreshtheNavigationpanel(afterthepackageisreloaded)toreflectthe elementsupdatedstatus. To remove a system lock from an element 1 Ifyoudonotknowthenamesoftheserverfilesthatcorrespondtotheelement,use theLock StatuscommandinDeveloper.Fordetails,seeViewinganElements CorrespondingServerFilesonpage 98. Ontheserversfilesystem,removethereadonlypropertiesfromthefilesthat correspondtotheelementtomakethefileswritable. ReloadthepackageontheIntegrationServerthatcontainstheelement.Theupdated statusisreflectedintheIntegrationServerAdministrator.RefreshtheNavigation panelinDevelopertoviewtheupdatedstatus. Important! Ifyouaccidentallyappliedasystemlocktoanelementthatwasalready lockedbyanotheruser,removethesystemlockbutDO NOThavetheuserreloadthe packageinwebMethodsDeveloper.(ReloadingthepackageinDeveloperwill discardtheiredits.)Theusercanthensavetheelementwithoutlosingthechangeshe orshemadetoitwhileyouhadtheelementsystemlocked.

2 3

webMethods Developer Users Guide Version 7.1.1

97

4 Locking and Unlocking Elements

Viewing an Elements Corresponding Server Files

YoucanviewthenamesoftheserverfilesassociatedwitheverywebMethodselement. Thisisconvenientwhenanelementissystemlockedandyouneedtoconveythe elementsfilenamestotheserveradministrator. To view server files for an element 1 2 IntheNavigationpanel,selecttheelementsforwhichyouwanttoviewtheserverfile names. OntheFilemenu,clickLock Status. Thefollowingdialogboxshowstheserverfilesassociatedwithaflowservicenamed ApplyCreditMemo.Theseserverfilesaresystemlocked(thatis,theyarenotwritableon theserver). Viewing server files for element ApplyCreditMemo

Note: Afteraserveradministratorremovesasystemlockfromanelement,you mustreloadthepackageinwhichtheelementresidestoreflecttheunlocked status.

Automatically Unlocking Elements After Saving

Youcanchoosetoautomaticallyunlockflowservices,ISdocumenttypes,and specificationsafteryousavechangestothem.Thispreventsyoufromforgettingto unlockthem;however,itmaynotbethebestoptionifyousaveperiodicallywhileediting anelement. Important! WhenanIntegrationServerhastheVCSIntegrationfeatureenabled,the Automatically unlock upon saveoptionmust be disabled.

98

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

To automatically unlock flow services, IS document types, and specifications after saving
To

1 2 3 4

OntheToolsmenu,clickOptions.TheOptionsdialogboxappears. ClickGeneral. UnderNavigation Panel,selecttheAutomatically unlock upon savecheckbox. ClickOK.

Troubleshooting
Thissectionaddressescommonproblemsthatmayarisewhenimplementingcooperative developmentwithwebMethodscomponents.

Lock/Unlock Problems
The Lock for Edit and Unlock commands are disabled. Possiblecausesare: TheIntegrationServertowhichyouareconnectedmayhavethe watt.server.ns.lockingModepropertyconfiguredtonolockingorsystemlocking only.Fordetails,contactyourserveradministrator. Youhaveselectedmultipleelementstolockorunlockandyourselectioncontainsof oneormoreofthefollowing:

Aserver Afolderorpackageanditscontents Apackageandanyotherelement Anadapternotificationrecord

When I try to lock an element, I get an exception message. Theelementmaybelockedbysomeoneelse,systemlocked(markedreadonlyonthe server),oryoumaynothaveWriteaccess.RefreshtheNavigationpanel.Ifalockisnot shownbutyoustillcannotlocktheelement,reloadthepackage.Inaddition,makesure thatyouareamemberoftheACLassignedforWriteaccesstotheelementbychecking theelementsPermissionspropertyinthePropertiespanel. I cant unlock a Java or C service. IfthereisanotherJavaorCservicethatislockedbyanotheruserorsystemlockedinthe samefolder,thenyoucannotunlockanyJavaorCservicesinthatfolder.Thisisbecause thoseservicessharethesame.javaand.classfilesontheIntegrationServer. I cant unlock elements since I changed my username. Youcanonlyunlockelementsthatyouhavelockedwithyourcurrentusernameforthe session.Ifyouhavechangedusernames,logbackintotheserverwithyouroldusername andthenunlocktheelements.

webMethods Developer Users Guide Version 7.1.1

99

4 Locking and Unlocking Elements

Iftheadministratorhasdeletedyourusername,contacthimorhertounlocktheelements ontheserver.YoucanassisttheadministratorbyusingtheLock Statuscommandto identifythenamesofthesystemlockedfilesontheserverthatneedtobeunlocked. Another user unlocked an element, but it still shows as locked in my Navigation panel. IfitisaJavaorCservice,reloadthepackageintheNavigationpanel.Ifitisanyother element,usetheRefreshcommandtorefreshtheNavigationpanel. I receive an element failed to unlock message when I try to unlock elements in the Integration Server Administrator. Thisindicatesthattheserverfilesforthelockedelementweredeletedfromtheserver. YouneedtoupdatetheIntegrationServerAdministratorslistofunlockedelementsby clickingSync to Name SpaceontheUnlockSelectedElementsscreen.TheSync to Name Spacecommandrunsautomaticallywhentheserverisstartedorrestarted.

Package Management Problems

I cant preserve locking information when I replicate and publish a package. Thisisexpectedbehaviorandispartofthefeaturesdesign.Youcan,however,preserve systemlocks(readonlyfileattributes). When I disable a package, it does not preserve locking information. Thisisexpectedbehaviorandpreventsconflictsifanotherpackagewiththesamefolder andelementnamesgetsinstalled.

Save Problems
When I try to save an element that I have locked, I get an exception message. Duringthetimethatyouhadthelock,theelementbecamesystemlocked,itsACLstatus changed,oraserveradministratorremovedyourlockandanotheruserlockedthe element.Iftheexceptionmessageindicatesthatafileisreadonly,thenoneorallofthe filesthatpertaintothatelementontheserveraresystemlocked.Contactyour administratortoremovethesystemlock.Afterthisisdone,youcansavetheelementand yourchangeswillbeincorporated. IftheexceptionmessageindicatesthatyoucannotperformtheactionwithoutACL privileges,thentheACLassignedtotheelementhasbeenchangedtoanACLinwhich youarenotanAlloweduser.Topreserveyourchangestotheelement,contactyour serveradministratorto: 1 2 3 4 Removeyourlockontheelement. Locktheelement. EdittheACLassignedforWriteaccesstotheelement,togiveyouaccess. Unlocktheelement.

Youcanthensaveyourchangestotheelement.

100

webMethods Developer Users Guide Version 7.1.1

4 Locking and Unlocking Elements

When I try to save a template, I get an error message. Thetemplatefileontheserverisreadonly.Contactyourserveradministratortomake thefilewritable.

Other Problems
I cant create a new Java or C service. AnotherJavaorCserviceislockedinthefolderinwhichyouwanttocreatethenew service,oryoudonothaveWriteaccesstoallJavaorCservicesinthefolder.Allofthem mustbeunlockedorlockedbyyouandyoumusthaveWriteaccesstoaddanewJavaor Cservicetothesamefolder.SeeLock/UnlockProblemsonpage 99. I cant delete a package. Oneoftheelementsinthatpackageissystemlocked(readonly)orlockedbyanother user.Contactyouradministratororcontacttheuserwhohastheelementlockedinthe package. The webMethods Integration Server went down while I was locking or unlocking an element. Theactionmayormaynothavecompleted,dependingontheexactmomentatwhichthe serverceasedaction.Whentheserverisbackup,restoreyoursessionandlookatthe currentstatusoftheelement.

Frequently Asked Questions

What is the difference between a system-locked element and a read-only element? None.Systemlockisatermusedtodenoteanelementthathasreadonlyfilesonthe webMethodsIntegrationServer.Theserveradministratorusuallyappliessystemlocksto files(makesthemreadonly). Can I select multiple elements to lock or unlock in the Navigation panel simultaneously? Yes,youcanselectmultipleelementstolockorunlockintheNavigationpanel,aslongas yourselectiondoesnotcontainthefollowing: Aserver Afolderorpackageanditscontents Apackageandanyotherelement Anadapternotificationrecord Youcanalsolockorunlockallelementsinapackageorfolderthathavenotbeen previouslylocked/unlockedbyrightclickingthepackageorfolderandselectingLock for Edit(tolock)orUnlock(tounlock). I only save elements after Im completely done. Remembering to unlock elements after saving them is tedious. Is there a shortcut for this task? Yes.Forthespecificprocedure,seeAutomaticallyUnlockingElementsAfterSavingon page 98.

webMethods Developer Users Guide Version 7.1.1

101

4 Locking and Unlocking Elements

Where is the lock information stored (such as names of elements that are locked, when they were locked, etc.)? TheinformationisstoredinternallyinRepositoryversion4,andintheVCSrepository,if youareusingVCS. Important! ItisnotrecommendedthatyouuseCooperativeDevelopmentfunctionality inanIntegrationServercluster.Lockinginformationforelementscouldbe inadvertentlysharedwithanotherIntegrationServerinthecluster.Useastandalone IntegrationServer,notacluster,whiledevelopingtoeliminatetheseCooperative Developmentproblems. Should I archive derived files? Generally,youshouldnotarchivederivedfilessuchasthe.classfilethatisgenerated whenyoucompileaJavaservice. What happens to the locks on elements when I replicate a package? Lockinginformationisnotpreservedwhenyoureplicateandpublishapackage.Thisis expectedbehaviorandispartofthefeaturesdesign.Youcan,however,preservesystem locks(readonlyfileattributes).

102

webMethods Developer Users Guide Version 7.1.1

Assigning and Managing Permissions

104 106 109 111 112

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning ACLs to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing ACL Information on a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

103

5 Assigning and Managing Permissions

Basic Concepts
Inadditiontocontrollingaccesstoelementsonanindividualuserbasisusinglocking, youcanalsocontrolaccessbygroupsofusersusingaccesscontrollists(ACLs).Typically createdbyasystemadministrator,ACLsallowyoutorestrictaccessonabroaderlevel. Forexample,ifyouhaveaproductionpackageandadevelopmentpackageonthe webMethodsIntegrationServer,youcanrestrictaccesstotheproductionpackageto usersinanAdministratorsACL,andrestrictaccesstothedevelopmentpackagetousers inaDevelopersACL. WithinACLs,youcanalsoassigndifferentlevelsofaccess,dependingontheaccessthat youwantdifferentgroupsofuserstohave.Forexample,youmaywantaTesterACL toonlyhaveReadandExecuteaccesstoelements.Or,youmaywantaContractorACL thatdeniesListaccesstosensitivepackagesonthewebMethodsIntegrationServer,so thatcontractorsneverseetheminwebMethodsDeveloper.

What Is an ACL?
AnACLcontrolsaccesstopackages,folders,andotherelements(suchasservices,IS documenttypes,andspecifications)atthegrouplevel.AnACLidentifiesgroupsofusers thatareallowedtoaccessanelement(AllowedGroups)and/orgroupsthatarenot allowedtoaccessanelement(DeniedGroups).WhenidentifyingAllowedGroupsand DeniedGroups,youselectfromgroupsthatyouhavedefinedpreviously. Therearefourdifferentkindsofaccess:List,Read,Write,andExecute. Listcontrolswhetherauserseestheexistenceofanelementanditsmetadata;thatis, itsinputandoutput,settings,andACLpermissions.Theelementwillbedisplayed onscreensintheDeveloperandtheIntegrationServerAdministrator. Readcontrolswhetherausercanviewthesourcecodeandmetadataofanelement. Writecontrolswhetherausercanupdateanelement.Thisaccessalsocontrols whetherausercanlock,rename,ordeleteanelementorassignanACLtoit. Executecontrolswhetherausercanexecuteaservice. Formoredetailsaboutthesetypesofaccess,seethewebMethodsIntegrationServer AdministratorsGuide.

What Happens When a Client Runs a Service with ACLs?

WhenaclientrequeststhatwebMethodsIntegrationServerinvokeaservice,theserver checkstheACLassignedtotheservice.Iftheclientisamemberofanallowedgroupand isnotamemberofadeniedgroup,theserverexecutestheservice.Iftheclientisnota memberofanallowedgroup,theserverdeniestherequesttoinvoketheserviceand stopsexecuting. Bydefault,whenaclientrequestsaservice,webMethodsIntegrationServerchecksonly theACLoftheexternallyinvokedservice(theservicerequesteddirectlybytheclient).

104

webMethods Developer Users Guide Version 7.1.1

5 Assigning and Managing Permissions

TheserverdoesnotchecktheACLsofanyoftheinternallyinvokedservices(those servicesinvokedbytheexternallyinvokedservice).However,youcansetupthesecurity settingsforaservicesothatwebMethodsIntegrationServercheckstheACLassignedto theserviceeverytimeitisinvoked,whetherdirectlybyaclientorbyanotherservice.For details,seeThePermissionsPropertiesonpage 107. ThefollowingdiagramillustratesthepointsatwhichACLcheckingoccurswhenaclient requestsaservice. ACL checking when a client requests a service
webMethods Integration Server Client

Purch:SubmitPO Purch:SubmitPO INVOKE Purch:LogPO INVOKE Purch:CreditAuth INVOKE Purch:SendPO

2 3 4

Purch:LogPO Purch:CreditAuth Purch:SendPO

Stage
1

Description Theclient(suchasanotherapplicationoraDSP)requeststhePurch:SubmitPO serviceonthelocalwebMethodsIntegrationServer.webMethodsIntegration ServercheckstheACLofthePurch:SubmitPOservice(theexternallyinvoked service).Theserverexecutestheserviceonlyiftheclientisinvokingtheservice onthebehalfofauserthatisamemberofanallowedgroupandisnota memberofadeniedgroupfortheACLassignedtotheservice. ThePurch:SubmitPOserviceinvokesthePurch:LogPOservice.Becausethe Purch:LogPOserviceisinvokedbytheexternallyinvokedserviceandislocated onthesameserverastheexternallyinvokedservice,webMethodsIntegration ServerconsidersthePurch:LogPOservicetobeinternallyinvoked. Consequently,theserverdoesnotchecktheACLofthePurch:LogPOservice beforeexecutingit. ThePurch:SubmitPOserviceinvokesthePurch:CreditAuthservice.Likethe Purch:LogPO service,webMethodsIntegrationServerconsidersthe Purch:CreditAuthservicetobeaninternallyinvokedservice.Consequently,the serverdoesnotchecktheACLofthePurch:CreditAuthservicebeforeexecutingit. ThePurch:SubmitPOserviceinvokesthePurch:SendPOservice.LikethePurch:LogPO andPurch:CreditAuthservices,webMethodsIntegrationServerconsidersthe Purch:SendPOservicetobeaninternallyinvokedservice.Theserverdoesnot checktheACLofthePurch:SendPOservicebeforeexecutingit.

webMethods Developer Users Guide Version 7.1.1

105

5 Assigning and Managing Permissions

Note: Ifthesecuritysettingsforthe Purch:LogPO,Purch:CreditAuth,orPurch:SendPO servicesspecifythatACLcheckingoccurseverytimetheserviceisinvoked(Enforce execute ACLoptionissettoAlways),webMethodsIntegrationServerwouldperform ACLcheckingwhentheexternallyinvokedservice(Purch:SubmitPO)invokedthese services.FormoreinformationaboutrequiringACLchecking,seeAssigningACLs toElementsonpage 106. Note: AnyservicethatthePurch:SubmitPOflowserviceinvokescouldalsobeinvoked directlybytheclient.Forexample,iftheclientdirectlyinvokesthePurch:SendPO service,theservercheckstheACLofthePurch:SendPOservice.Iftheclientisinvoking theserviceonthebehalfofauserthatisamemberofanallowedgroupandnota memberofadeniedgroup,thentheserverexecutesthePurch:SendPO service.

Am I Required to Use ACLs?

No.However,therearedefaultACLsettingsforelementsshippedwiththeIntegration Serveranddefaultsettingsfornewelementsthatyoucreate.FordetailsondefaultACLs, seethewebMethodsIntegrationServerAdministratorsGuide.

How Do I Create an ACL?

YoucreateACLsusingtheIntegrationServerAdministrator.Fordetails,seethe webMethodsIntegrationServerAdministratorsGuide.

Assigning ACLs to Elements

YoucanassignanACLtoapackage,folder,services,andotherelementsinthe Navigationpanel.AssigninganACLrestrictsorallowsaccesstoanelementforagroup ofusers.YoucanassignonlyoneACLperelement. YoucannotassignanACLtoanelementforList,Read,orWriteaccessunlessyouarea memberofthatACL.Forexample,ifyouwanttoallowDevTeam1toedittheProcessPO service,youmustbeamemberoftheDevTeam1ACL.Thatis,yourusernamemustbea memberofagroupthatisintheAllowedlistoftheDevTeam1ACL. To assign an ACL to a package or folder 1 MakesurethattheACLyouwanttoassignexistsontheIntegrationServer.Ifnot, createtheACLintheIntegrationServerAdministrator.Fordetails,seethe webMethodsIntegrationServerAdministratorsGuide. IntheNavigationpanel,clickthepackageorfoldertowhichyouwanttoassignan ACL. OntheFilemenu,clickOpen.

2 3

106

webMethods Developer Users Guide Version 7.1.1

5 Assigning and Managing Permissions

4 5

Intheeditor,clickthetitlebarofthepackageorfoldertogiveitthefocus. InthePermissionscategoryofthePropertiespanel,selecttheACLsthatyouwantto assignforeachlevelofaccess.Fordetails,seeThePermissionsPropertieson page 107. Important! ForList,Read,andWriteaccess,youcanonlyassignACLsofwhichyou areamember.IfyoucannotassignanACLtoanelementforList,Read,orWrite access,youprobablyarenotamemberofausergroupintheAllowedlistofthat ACL.Toverify,usetheToolsACL Informationcommand.Toobtainaccesstoan ACL,contactyourserveradministrator.

Savetheelement.Ifanerrormessageappears,checktomakesurethatyouarea memberofeachACLthatyouassignedtotheelement.
To assign an ACL to other elements in the Navigation panel

To

MakesurethattheACLyouwanttoassignexistsontheIntegrationServer.Ifnot, createtheACLintheIntegrationServerAdministrator.Fordetails,seethe webMethodsIntegrationServerAdministratorsGuide. OpentheelementtowhichyouwanttoassignanACL. InthePermissionscategoryofthePropertiespanel,selecttheACLsthatyouwantto assignforeachlevelofaccess.Fordetails,seeThePermissionsPropertieson page 107. Important! ForList,Read,andWriteaccess,youcanonlyassignACLsofwhichyou areamember.IfyoucannotassignanACLtoanelementforList,Read,orWrite access,youprobablyarenotamemberofausergroupintheAllowedlistofthat ACL.Toverify,usetheToolsACL Informationcommand.Toobtainaccesstoan ACL,contactyourserveradministrator.

2 3

Savetheelement.Ifanerrormessageappears,checktomakesurethatyouarea memberofeachACLthatyouassignedtotheelement.

The Permissions Properties

YouassignanACLtoanelementinthePermissionscategoryofthePropertiespanel. Dependingontheelementyouselect,certainaccesslevelsaredisplayed.Forexample,for apackage,youcanonlysetListaccess.Fordetailsaboutthedifferentlevelsofaccess availableforelements,seethewebMethodsIntegrationServerAdministratorsGuide. TheACLsassignedtoanelementaremutuallyexclusive;thatis,anelementcanhave differentACLsassignedforeachlevelofaccess.Forexample,thefollowingelementhas theDevelopersACLassignedforReadaccessandtheAdministratorsACLassignedfor Writeaccess.

webMethods Developer Users Guide Version 7.1.1

107

5 Assigning and Managing Permissions

Permissions properties for a flow service

An element can have different ACLs assigned for each level of access.

Field / Button List ACL Read ACL Write ACL Execute ACL Enforce execute ACL

Description UsersintheAllowedlistofthisassignedACLcanseethattheelement existsandviewtheelementsmetadata(input,output,etc.). UsersintheAllowedlistofthisassignedACLcanviewthesourcecode andmetadataoftheelement. UsersintheAllowedlistofthisassignedACLcanlock,edit,rename, anddeletetheelement. UsersintheAllowedlistofthisassignedACLcanexecutetheservice. Thislevelofaccessonlyappliestoservices. When top-level service only.TheIntegrationServerperformsACL checkingagainsttheservicewhenitisdirectlyinvokedfromaclient orDSP.Forexample,supposeaclientinvokestheOrderPartsservice onserverA.Aftercheckingportaccess,serverAcheckstheExecute ACLassignedtoOrderPartstomakesuretherequestinguseris allowedtoruntheservice.ItdoesnotchecktheExecuteACLwhen otherservicesinvokeOrderParts. Always.TheIntegrationServerperformsACLcheckingagainstthe servicewhenitisdirectlyinvokedfromaclientaswellaswhenitis invokedfromotherservices.Forexample,supposetheOrderParts serviceisinvokedfromabrowser,aswellasbytheProcessOrderand AddToDatabaseservices.IfAlwaysissetonOrderParts,theserver performsACLcheckingonOrderPartsthreetimes(oncewhenitis invokedfromthebrowserandtwicewhenitisinvokedby ProcessOrderandAddToDatabase).

Note: YoucanviewtheusersandgroupsthatcomposetheACLsontheIntegration ServertowhichyouareconnectedbyusingtheToolsACL Informationcommand.This informationisreadonly;toeditACLs,users,andgroups,usetheIntegrationServer Administrator.

108

webMethods Developer Users Guide Version 7.1.1

5 Assigning and Managing Permissions

ACLs and Inheritance

WhenyouassignanACLtoafolder,itaffectsthesubfoldersandservicesinthefolder. ThesubfoldersandservicesthatdonothaveanassignedACLinherittheACLsthatyou assigntothefolder.(SubfoldersandserviceswithanassignedACLarenotaffectedby theACLassignedtothefolder.)WhenasubfolderorserviceinheritstheACLofafolder, inheritedisdisplayednexttotheACLintheList,Read,Write,orExecutefieldsinthe PermissionscategoryofthePropertiespanel. WhenyouremoveanACLfromaserviceorsubfolder,theserviceorsubfolderinherits theACLassignedtothefolderinwhichtheserviceorsubfolderislocated.Whenyou removetheACLassignedtothetoplevelfolder(theuppermostfolderinapackage), webMethodsIntegrationServerappliesthedefaultACLtothefolderanditscontentsfor whichanACLisnotspecified.(ThedefaultACLrestrictsaccesstoaservicetoanyuser withavalidusernameandpasswordforthewebMethodsIntegrationServer.)

Default ACLs and Inheritance

Iftheelementisatoplevelfolder,itsdefaultACListhatspecifiedbyaconfigurationfile, notbyitsparent(thepackage).Iftheelementisasubfolder,itsharesitsdefaultACL settingswithotherfoldersatthesamelevelinthefolderhierarchy.Fordetailsabout inheritance,aswellasthedefaultACLsthatareinstalledwiththewebMethods IntegrationServer,seethewebMethodsIntegrationServerAdministratorsGuide. Note: Anelementcaninheritaccessfromallelementsexceptapackage.

Viewing ACL Information on a Server

YoucanviewtheusersandgroupsthatmakeuptheACLsonaserverbyusingthe ToolsACL Informationcommand.TheACLInformationdialogboxliststheACLs containedontheIntegrationServertowhichyouareconnected.Thisinformationisread only;toeditACLs,users,andgroups,usetheIntegrationServerAdministrator.

webMethods Developer Users Guide Version 7.1.1

109

5 Assigning and Managing Permissions

ACL Information dialog box for a Server

The Default ACL... ...denies access to members of the Anonymous group...

...and allows access to members of all other groups.

Field ACLs

Description TheACLsdefinedontheIntegrationServertowhichyouare connected.TheseincludethedefaultACLsthatwereinstalledwith theserver. Allowed.Theusergroup(s)thathavebeenexplicitlyallowedto accessthepackages,folders,services,orotherelements associatedwiththisACL. Denied.Theusergroup(s)thathavebeenexplicitlydeniedaccess tothepackages,folders,services,orotherelementsassociated withthisACL.

User Group Association for [ACL]

Resulting Users for [ACL]

ThenamesofusersthattheACLauthorizes,giventhecurrent settingsintheAllowedandDeniedlists.Theserverbuildsthislistby lookingatthegroupstowhicheachuserbelongsandcomparing thattothegroupstowhichtheACLallowsordeniesaccess.For detailsonhowtheserverdeterminesaccess,seethewebMethods IntegrationServerAdministratorsGuide.

110

webMethods Developer Users Guide Version 7.1.1

5 Assigning and Managing Permissions

How ACLs Affect Other Developer Features

ACLs and Locking
Asexplainedpreviously,lockingallowsyoutocontrolaccessattheindividualuserlevel, whileACLsallowyoutocontrolaccessbygroupsofusers.Followingareguidelinesto keepinmindasyouuseACLswithlocking: Tolockanelement,youmustbethememberoftheACLthatisassignedforWrite accesstothatelement. TolockaJavaorCservicewithinafolder,youmustbethememberoftheACLthatis assignedforWriteaccessforallJavaorCservicesinthatfolder.Thisisbecause lockingandunlockingactionsforJava/Cservicesareatthefolderlevel.Fordetails, seetheChapter 4,LockingandUnlockingElements. ToeditACLpermissionsforanelement,youmustlocktheelement(exceptfor packagesandfolders,whichcannotbelocked). Note: WhenanIntegrationServerhastheVCSIntegrationfeatureenabled,anelement islockedwhenitischeckedoutoftheversioncontrolsystem.Withtheappropriate ACLpermissions,youareabletocheckout(lock)andcheckin(unlock)elements, foldersandpackages.

ACLs and Testing/Debugging Services

Keepthefollowinginmindwhenyoutestanddebugservices: Tosteportracethroughatoplevelservice,youmusthaveExecute,Read,andList accesstotheservice. Tosteportracethroughalltheserviceswithinatoplevelservice,youmusthave Execute,List,andReadaccesstoallservicesinvokedbythetoplevelservice.Ifyou donothaveaccesstoservicesinvokedbythetoplevelservice,Developersteps overthoseservices.(TheIntegrationServerperformsACLcheckingforachild servicewhentheEnforce execute ACLpropertyfortheserviceissettoAlways.) Developerexecutesthetoplevelserviceandcontinuestothenextflowstep. Developerdoesnotstepintoortraceintothetoplevelservice. TotestaservicebysendinganXMLfiletoaservice,youmusthaveReadaccesstothe service. Tosetabreakpointinaservice,youmusthaveReadaccesstotheservice.

webMethods Developer Users Guide Version 7.1.1

111

5 Assigning and Managing Permissions

ACLs and Creating, Viewing, and Deleting Elements

Keepthefollowingguidelinesinmindwhenyoucreate,view,ordeleteelements: Tocreateorpasteanelement,youmusthaveWriteaccesstoitsparentfolder.Ifyou arenotamemberoftheACLassignedforWriteaccesstothefolder,contactyour serveradministrator. Tocopyanelement,youmusthaveReadaccesstoitandWriteaccesstoitsparent folder. Torenameordeleteanelement,youmusthaveWriteaccesstoitanditsparentfolder. Tocopyapackage,youmustbeamemberofagroupassignedtotheReplicators ACL. WhenyoucreateafolderandassignanACLtoit,anyelementsthatyoucreatewithin thatfolderinherititsACL,untilyouexplicitlysettheACLtosomethingelse.For detailsaboutinheritance,seethewebMethodsIntegrationServerAdministratorsGuide. YoumaynotseealloftheelementsontheIntegrationServerintheNavigationpanel becauseyoumaynothaveListaccesstoallofthem.Youcanonlyseethoseelements towhichyouhaveatleastListaccess.

Troubleshooting
I receive a Cannot perform operation without Write ACL privileges message when I try to create an element. YouarenotamemberoftheACLassignedtothefolderinwhichyouwanttosavethe element.Toverify,checkthePermissionscategoryofthePropertiespanel.Ifyouhad previouslybeenabletosavetheelement,theACLsettingsmayhavechangedonthe serversinceyoulastsavedit.SeeTroubleshootingonpage 99inChapter 4,Locking andUnlockingElements. I receive an element already exists message when I try to create an element. TheremaybeanelementwiththesamenameontheIntegrationServer,butyoumaynot beabletoseeitbecauseyoudonothaveListaccesstoit.Tryadifferentelementname,or contactyourserveradministrator. I cant assign an ACL to an element. MakesurethatyouhavelockedtheelementandthatyouareamemberoftheList,Read, orWriteACLthatyouwanttoassign.Toverify,usetheToolsACL Informationcommand. I cant see the source of a flow or Java service. However, I can see the input and output. YoudonothaveReadaccesstotheservice.Contactyourserveradministratortoobtain access. I receive an exception when I try to lock an element. Theelementmaybelockedbysomeoneelse,systemlocked(markedreadonlyonthe server),oryoumaynothaveWriteaccess.RefreshtheNavigationpanel.Ifalockisnot shownbutyoustillcannotlocktheelement,reloadthepackage.Inaddition,makesure

112

webMethods Developer Users Guide Version 7.1.1

5 Assigning and Managing Permissions

thatyouareamemberoftheACLassignedforWriteaccesstotheelement.Todoso,click thePermissionscategoryofthePropertiespanel. I receive an error when I run a command on the Test menu. YoumusthaveaminimumofReadaccesstotraceorstepthroughaservice.Ifyoudont haveReadaccesstotheservicewhenyouaretracing,tracinginto,steppingthrough,or steppingintoaservice,youwillreceiveanerrormessage. IfyoudohaveReadaccesstoaservicebutyoudonothaveReadaccesstoaserviceit invokes,Developerstepsovertheinvokedservicebutdoesnotdisplayanerror message. YoumustalsohaveReadaccesstoaservicetosetabreakpointintheserviceorsendan XMLdocumenttotheservice. I receive an exception when I try to go to a referenced service from the pipeline. YoudonothaveListaccesstothereferencedservice.Contactyourserveradministrator. I receive a Couldnt find in Navigation panel message when I try to find a service in the Navigation panel. However, I know it is on the Integration Server. IfyoudonotseetheservicelistedintheNavigationpanel,youprobablydonothaveList accesstothatservice.Contactyourserveradministrator. I cant copy and paste a Java service. ChecktomakesurethatyouhaveWriteaccesstoallJavaservicesinthefolderintowhich youwanttopastetheservice,aswellasWriteaccesstothefolderitself.

webMethods Developer Users Guide Version 7.1.1

113

5 Assigning and Managing Permissions

114

webMethods Developer Users Guide Version 7.1.1

Building Flow Services

116 120 120 122 127 129 135 137 140 149

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Declaring Input and Output Parameters for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning an Output Template to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Universal Names to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

115

6 Building Flow Services

Basic Concepts
Tosuccessfullybuildaflowservice,youshouldunderstandthefollowingbasicconcepts andterms.

What Is a Flow Service?

AflowserviceisaservicethatiswritteninthewebMethodsflowlanguage.Thissimple yetpowerfullanguageletsyouencapsulateasequenceofserviceswithinasingleservice andmanagetheflowofdataamongthem.Forexample,youmightcreateaflowservice thattakesapurchaseorderfromabuyerandexecutesthefollowingseriesofservices beforesubmittingittoaninternalorderingsystem: 1 2 3 4 Getsapurchaseordersubmittedbyabuyer Logstheorderinanaudittrailfile Performsacreditcheck Poststheordertotheorderingsystem

Flow services encapsulate other services

Client application invokes Purch:SubmitPO... Purch:SubmitPO Purch:SubmitPO

INVOKE Purch:GetOrders INVOKE Purch:LogOrder INVOKE Purch:CreditAuth INVOKE Purch:PostPO

2 3 4

...which performs a sequence of four services

Anyservicecanbeinvokedwithinaflow(includingotherflowservices).Forinstance,a flowmightinvokeaservicethatyoucreate,anyofthebuiltinservicesprovidedwiththe webMethodsIntegrationServer,and/orservicesfromawebMethodsaddonproduct suchasthewebMethodsJDBCAdapter. YoucreateflowservicesusingDeveloper.TheyaresavedinXMLfilesonwebMethods IntegrationServer. Important! AlthoughflowservicesarewrittenasXMLfiles,theyaremaintainedina formatthatcanonlybecreatedandunderstoodbyDeveloper.Youcannotcreateor editaflowservicewithatexteditor.

116

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

What Is a Flow Step?

Aflowservicecontainsflowsteps.Aflowstepisabasicunitofwork(expressedinthe webMethodsflowlanguage)thatwebMethodsIntegrationServerinterpretsandexecutes atruntime.ThewebMethodsflowlanguageprovidesflowstepsthatinvokeservicesand flowstepsthatletyoueditdatainthepipeline. webMethodsflowlanguagealsoprovidesasetofcontrolstepsthatallowyoutodirectthe executionofaflowserviceatruntime.Thecontrolstepsallowyouto: Conditionallyexecuteaspecifiedsequencebasedonafieldvalue. Retryaspecifiedsequenceuntilitsucceeds. Repeataspecifiedsequence(loop)foreachelementinanarrayfield. Inthefollowingflowservice,controlstepshavebeeninsertedtoloopthroughasubsetof theflowserviceandbranchtooneoftwoservicesinthelaststepoftheloop. Control steps are used to direct the execution of a flow
Purch:SubmitPO Purch:SubmitPO

INVOKE Purch:GetOrders A LOOP step repeats a set of flow steps LOOP PurchaseOrders INVOKE Purch:LogOrder INVOKE Purch:CreditAuth A BRANCH step selects a specified flow step for execution BRANCH AuthOK INVOKE Purch:PostPO INVOKE Purch:BouncePO

Aflowservicecancontainthefollowingtypesofflowsteps: Invocation Steps INVOKE Data-Handling Steps MAP Performsspecifiededitingoperationsonthepipeline(suchas mappingvariablesinthepipeline,addingvariablestothe pipeline,anddroppingvariablesfromthepipeline).Formore informationaboutthisstep,seeTheMAPSteponpage 183. Executesaspecifiedservice.Formoreinformationaboutthis step,seeTheINVOKESteponpage 157.

webMethods Developer Users Guide Version 7.1.1

117

6 Building Flow Services

Control Steps BRANCH Executesaspecifiedflowstepbasedonthevalueofaspecified variableinthepipeline.Formoreinformationaboutthisstep, seeTheBRANCHSteponpage 160. Executesasetofflowstepsonceforeachelementina specifiedarray.Formoreinformationaboutthisstep,seeThe LOOPSteponpage 178. Reexecutesasetofflowstepsuptoaspecifiednumberof timesbasedonthesuccessfulornonsuccessfulcompletionof theset.Formoreinformationaboutthisstep,seeThe REPEATSteponpage 170. Groupsasetofflowstepsintoaseries.TheSEQUENCEstepis implicitinmostflowservices(thatis,thestepsinaflow servicearetreatedasaseries).However,attimesitis necessarytoexplicitlygroupasubsetofflowstepsusing SEQUENCEsothattheycanbetreatedasaunit.Formore informationaboutthisflowstep,seeTheSEQUENCEStep onpage 176. Controlstheexecutionofaflowstep(forexample,abortan entireflowservicefromwithinaseriesofdeeplynestedsteps, throwanexceptionwithoutwritingaJavaservice,orexita LOOPorREPEATwithoutthrowinganexception).Formore informationaboutthisstep,seeTheEXITSteponpage 181.

LOOP

REPEAT

SEQUENCE

EXIT

SeeAppendix A,webMethodsFlowStepsforadetaileddescriptionofeachtypeof flowstepprovidedbythewebMethodsflowlanguage.Forinformationaboutbuilding eachtypeofflowstep,seeChapter 7,InsertingFlowSteps.

What Is the Pipeline?

Thepipelineisthegeneraltermusedtorefertothedatastructureinwhichinputand outputvaluesaremaintainedforaflowservice.Itallowsservicesintheflowtoshare data. Thepipelinestartswiththeinputtotheflowserviceandcollectsinputsandoutputsfrom subsequentservicesintheflow.Whenaserviceintheflowexecutes,ithasaccesstoall datainthepipelineatthatpoint.

118

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

The pipeline holds the input and output for a flow service
Services in a flow get their input from and place their output in the pipeline. Flow Service input INVOKE Purch:LogPO output input INVOKE Purch:CreditAuth output input INVOKE Purch:ConvertDate output input INVOKE Purch:SendPO output The Pipeline ONum:46-77135 Name:Kings Sport Phone:201-887-1544 TNum:128824993554 Acct:128824993554 Total:5732.78 Qty:20 AuthNum:TW99123554 Date:04/04/99 Item:PK8801-NS OrderDate:19990404 Ship:UPS Ground Terms:30N Freight:65.00 Status:Received

Whenyoubuildaflowservice,youuseDevelopertospecifyhowinformationinthe pipelineismappedtoandfromservicesintheflow.

What Are Input and Output Parameters?

Inputandoutputparametersarethenamesandtypesoffieldsthattheservicerequiresas inputandgeneratesasoutput.Forexample,aservicethattakestwostringvaluesan accountnumber(AcctNum)andadollaramount(OrderTotal)asinputandproducesan authorizationcode(AuthCode)asoutput,hasthefollowinginputandoutputparameters: Input and output parameters define the fields that the service requires as input and generates as output Input Name AcctNum OrderTotal Data Type String String Output Name AuthCode Data Type String

Partoftheprocessofcreatingaserviceisdeclaringitsinputandoutputparameters(that is,explicitlyspecifyingthefieldsitexpectsasinputandproducesasoutput).

webMethods Developer Users Guide Version 7.1.1

119

6 Building Flow Services

A Process Overview
Buildingaflowserviceisaprocessthatinvolvesthefollowingbasicstages:
Stage 1

Creating a new service on webMethods Integration Server.Duringthisstage, youcreatethenewserviceonthewebMethodsIntegrationServerwhere youwilldoyourdevelopmentandtesting.Forinformationaboutthis stage,seeCreatingaNewFlowServicewhichfollows. Inserting flow steps into the new service. Duringthisstage,youspecifythe workthatyouwanttheservicetoperformbyaddingflowstepstothe service.Forinformationaboutthisstage,seeChapter 7,InsertingFlow Steps. Declaring the input and output parameters of the service. Duringthisstage,you definetheservicesinputsandoutputs.Forinformationaboutthisstage, seeDeclaringInputandOutputParametersforaServiceonpage 122. Mapping pipeline data. Duringthisstage,yourouteinputandoutput variablesbetweenservicesthatareinvokedintheflow.Forinformation aboutthisstage,seeChapter 8,MappingDatainaFlowService. Specifying the run-time parameters.Duringthisstage,youassignparameters thatconfiguretheruntimeenvironmentforthisservice.Forinformation aboutthisstage,seeSpecifyingRunTimeParametersonpage 129. Formatting service output.Duringthisstageyoucancreateanoutput templatetoformattheserviceoutput.Forinformationaboutthisstage, seeAssigninganOutputTemplatetoaServiceonpage 127orreferto theDynamicServerPagesandOutputTemplatesDevelopersGuide. Testing and debugging. Duringthisstageyoucanusethetoolsprovidedby Developertotestanddebugyourflowservice.Forinformationaboutthis stage,seeChapter 11,TestingandDebuggingServices.

Stage 2

Stage 3

Stage 4

Stage 5

Stage 6

Stage 7

Theremainingsectionsinthischapterandthefollowingchaptersprovidedetailed informationabouteachstage.

Creating a New Flow Service

Thefirststepyoutakewhenyoubuildaflowserviceistocreateanewserviceonthe webMethodsIntegrationServerwhereyoudoyourdevelopment.

Package and Folder Requirements

Beforeyoucreateanewflowservice,youmust: Make sure the package in which you want to create the flow service already exists.Ifthe packagedoesnotalreadyexist,createitusingDeveloper.Formoreinformationabout creatingapackage,seeCreatingaPackageonpage 72.

120

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Make sure the folder in which you want to create the service already exists and that you have Write ACL access to it.Ifthefolderdoesnotalreadyexist,createitusingDeveloper.For informationaboutcreatingfolders,seeCreatingNewElementsonpage 41.For informationaboutACLpermissions,seeChapter 5,AssigningandManaging Permissions. Oncethepackageandfolderareinplace,usetheFileNewcommandtostarttheprocess ofcreatinganewservice.Fordetails,seeCreatingNewElementsonpage 41.

Using the Default Logic Options

Thewizardthatcreatesanewflowservicegivesyoutheoptionofstartingwithanempty flow(onethatcontainsnopredefinedflowsteps)orstartingwithaservicethatcontainsa setofdefaultlogicforextractinginformationfromanHTMLorXMLdocument(a commonflowservicefunction). IfyouarebuildingaflowservicethatextractsdatafromanHTMLorXMLdocument, youcanselectanoptiontoautomaticallygeneratethelogic(thatis,thesetofflowsteps) thatwillgetdatafromaspecifieddocument,ratherthanbuildingthislogicmanually. Use this option... Empty Flow Load and Query an HTML Page To... Generateaflowservicethatdoesnothaveanylogic. AutomaticallygenerateaflowservicethatinvokestheloadXMLNode service(whichgetsadocumentfromaURLthatyouspecify)and thequeryXMLNodeservice(whichextractsaspecifiedsetofelements fromthedocumentreturnedbyloadXMLNode). ForadditionalinformationabouttheloadXMLNodeandqueryXMLNode services,seetheXMLServicesDevelopersGuide. Receive an XML Document AutomaticallygenerateaservicethatreceivesanXMLnodeas input.IfyouspecifytheformatbyprovidingaDTDorXMLSchema definition,webMethodsDevelopermapstheincomingdocumentto itscorrespondingISdocumenttypestructure.

Important! Theflowstepsproducedbytheseoptionsarenodifferentthanthose producedbymanuallyinsertingINVOKEloadXMLNodeandINVOKEqueryXMLNode stepsinaflowservice.AfterDeveloperinsertsthesetofdefaultstepsintoyourflow service,youcaneditthedefaultstepsandinsertadditionalstepsjustasyouwould anyordinaryflowservice.

Inserting Flow Steps

Flowstepscallpreviouslybuiltservicesanddirecttheflowofdatawithinaflowservice. Youcaninsertflowstepsintoaflowserviceusingthebuttonsatthetopoftheeditor.For moreinformation,seeChapter 7,InsertingFlowSteps.

webMethods Developer Users Guide Version 7.1.1

121

6 Building Flow Services

To insert a/an... INVOKEstep MAPstep BRANCHstep LOOPstep REPEATstep SEQUENCEstep EXITstep

Click this button...

Declaring Input and Output Parameters for a Service

Inputandoutputparametersarethenamesanddatatypesofthefieldsthataservice expectsasinputandgeneratesasoutput.Somesystemsrefertoinputandoutput parametersasimportsandexports.Theseparametersarealsocollectivelyreferredto asasignature. Youdeclareinputandoutputparametersforalltypesofservices:flowservices,Java services,andserviceswritteninothersupportedprogramminglanguages. Althoughyouarenotrequiredtodeclareinputandoutputparametersforaservice(the IntegrationServerwillexecuteaserviceregardlessofwhetherithasaspecificationor not),therearegoodreasonstodoso: Declaring parameters makes the services input and outputs visible to Developer. Without declaredinputandoutputparameters,youcannot:

Linkdatatoand/orfromtheserviceusingDevelopersPipelinetab. AssigndefaultinputvaluestotheserviceonthePipelinetab. Validatetheinputandoutputvaluesoftheserviceatruntime. TesttheserviceinDeveloperandenterinitialinputvalues. Generateskeletoncodeforinvokingtheservicefromaclient.

Declaring parameters makes the input and output requirements of your service known to other developerswhomaywanttocallyourservicefromtheirprograms. Forthesereasons,westronglyrecommendthatyoumakeitapracticetodeclareinput andoutputparametersforeveryservicethatyoucreate.

122

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Supported Data Types

webMethodsDevelopersupportsseveraldatatypesforuseinservices.Eachdatatype supportedbyDevelopercorrespondstoaJavadatatypeandhasanassociatedicon. Whenworkingintheeditor,youcandeterminethedatatypeforafieldbylookingatthe iconnexttothefieldname. Forinformationaboutthesedatatypesandtheeditoriconsthatrepresentthem,see Appendix C,SupportedDataTypes.

Specifying Input Parameters

Whenyoudefinetheinputparametersforaflowservice,keepthefollowingpointsin mind: Specify all inputs that a calling program must supply to this flow service. Forexample,ifa flowserviceinvokestwootherservices,onethattakesafieldcalledAcctNumand anotherthattakesOrderNum,youmustdefinebothAcctNumandOrderNumasinput parametersfortheflowservice. Note: Thepurposeofdeclaringinputparametersistodefinetheinputsthata callingprogramorclientmustprovidewhenitinvokesthisflowservice.Youdo notneedtodeclareinputsthatareobtainedfromwithintheflowitself.For example,iftheinputforoneserviceintheflowisderivedfromtheoutputof anotherserviceintheflow,youdonotneedtodeclarethatfieldasaninput parameter. When possible, use variable names that match the names used by the services in the flow. Variableswiththesamenameareautomaticallylinkedtooneanotherinthepipeline. (Rememberthatvariablenamesarecasesensitive.)Ifyouusethesamevariable namesusedbyflowsconstituentservices,youreducetheamountofmanualdata mappingthatneedstobedone.Whenyouspecifynamesthatdonotmatchtheones usedbytheconstituentservices,youmustusethePipelinetabtomanuallylinkthem tooneanother.ForinformationaboutthePipelinetab,seeWhatDoesthePipeline TabContain?onpage 186. Avoid using multiple inputs that have the same name.AlthoughDeveloperpermitsyouto declaremultipleinputparameterswiththesamename,thefieldsmaynotbe processedcorrectlywithintheserviceorbyservicesthatinvokethisservice. Make sure the variables match the data types of the variables they represent in the flow. For example,ifaserviceintheflowexpectsadocumentlistcalledLineItems,definethat inputvariableasadocumentlist.Or,ifaserviceexpectsaDateobjectcalled EmploymentDate,definethatinputvariableasanObjectandapplythejava.util.Date objectconstrainttoit.Foracompletedescriptionofthedatatypessupportedby Developer,seeAppendix C,SupportedDataTypes. Declared input variables appear automatically as inputs in the pipeline.Whenyouselectthe firstserviceorMAPstepintheflow,thedeclaredinputsappearunderPipeline In.

webMethods Developer Users Guide Version 7.1.1

123

6 Building Flow Services

Important! Ifyoueditacachedservicebychangingtheinputs(notthepipeline),you mustresettheservercache.Ifyoudonotresetit,theoldcachedinputparameterswill beusedatruntime.ToresettheservicecachefromDeveloper,selecttheserviceand thenclicktheResetbuttonnexttoReset CacheinthePropertiespanel.Toresetthe servicecachefromIntegrationServerAdministrator,selectService UsageunderServer intheNavigationpanel.Selectthenameoftheserviceandaninformationscreenfor thatserviceappears.ClickReset Server Cache. Note: IfyouintendtousethisservicewithaBroker/localtriggeroraJMStrigger, makesuretheinputsignatureconformstotherequirementsforeachofthosetrigger types.FormoreinformationaboutcreatingBroker/localtriggers,seethePublish SubscribeDevelopersGuide.FormoreinformationaboutcreatingJMStriggers,seethe webMethodsIntegrationServerJMSClientDevelopersGuide.

Specifying Output Parameters

OntheoutputsideoftheInput/Output tabyouspecifythevariablesthatyouwanttheflow toreturntothecallingprogramorclient.Theguidelinesfordefiningtheoutput parametersaresimilartothosefordefininginputparameters: Specify all of the output variables that you want this flow service to returntothecalling programorclient. Make sure the names of output variables match the names used by the services thatproduce them.Likeinputvariables,ifyoudonotspecifynamesthatmatchtheonesproduced bytheflowsconstituentservices,youmustusethePipelinetabtomanuallylinkthem tooneanother.ForinformationaboutthePipelinetab,seeWhatDoesthePipeline TabContain?onpage 186. Avoid using multiple outputs that have the same name.AlthoughDeveloperpermitsyouto declaremultipleoutputparameterswiththesamename,thefieldsmaynotbe processedcorrectlywithintheserviceorbyservicesthatinvokethisservice. Make sure the variables match the data types of the variables they represent in the flow.For example,ifaserviceproducesaStringcalledAuthorizationCode,makesureyoudefine thatvariableasaString.Or,ifaserviceproducesaLongobjectcalledEmployeeID, definethatoutputvariableasanObjectandapplythejava.lang.Longobject constrainttoit.Foracompletedescriptionofthedatatypessupportedbyaservice, seeAppendix C,SupportedDataTypes. Declared output variables appear automatically as outputs in the pipeline. Whenyouselectthe lastserviceorMAPstepinaflow,thedeclaredoutputvariablesappearunderPipeline Out.

124

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Completing the Input/Output Tab

YoudeclaretheinputandoutputparametersforaserviceusingtheInput/Outputtab.On theleftsideofthistab,youdefinethevariablesthattheservicerequiresasinput.Onthe rightside,youdefinethevariablestheservicereturnstotheclientorcallingprogram. Input/Output tab

Define the flow services input parameters on this side...

...and output parameters on this side.

Foraflowservice,theinputsidedescribestheinitialcontentsofthepipeline.Inother words,itspecifiesthevariablesthatthisflowserviceexpectstofindinthepipelineatrun time.Theoutputsideidentifiesthevariablesproducedbytheflowserviceandreturned tothepipeline. Youcancompletethe Input/Outputtabinthefollowingways: Reference a specification. Aspecificationdefinesasetofserviceinputsandoutputs.You canuseaspecificationtodefineinputandoutputparametersformultipleservices. Whenyouassignaspecificationtoaservice,youcannotadd,delete,ormodifythe declaredvariablesusingtheservicesInput/Outputtab. Reference an IS document type. YoucanuseanISdocumenttypetodefinetheinputor outputparametersforaservice.WhenyouassignanISdocumenttypetotheInputor OutputsideoftheInput/Outputtab,youcannotadd,modify,ordeletethevariableson thathalfofthetab. YouinsertareferencetoanISdocumenttypeinoneofthreeways:

BytypingthefullyqualifiednameoftheISdocumenttypeintheInputorOutput field Byclicking toselectanISdocumenttypefromalist

BydragginganISdocumenttypeonthesameserverfromtheNavigationpanel totheboxbelowtheValidate inputorValidate outputcheckboxes

Withthefirsttwomethods,thevariableswithintheISdocumenttypebecomethe inputoroutputsignaturefortheservice.Youcannotadd,modify,ordeletethe variablesonthathalfofthetab.Withthethirdmethod,theISdocumenttype

webMethods Developer Users Guide Version 7.1.1

125

6 Building Flow Services

referencebecomesthetopleveldocumentinthesignature.Youcannotmodifyor deletethevariablesthatarecontainedwithinthereferencedISdocumenttypebut youcanaddothervariablestothathalfofthetab. Manually insert input and output variables.Use tospecifythedatatypeandnamefor eachinputandoutputvariablefortheservice. To declare input and output parameters for a service 1 2 3 Opentheserviceforwhichyouwanttodeclareinputandoutputparameters. Intheeditor,clickthe Input/Outputtabforthatservice. Ifyouwanttoreferenceaspecification,dothefollowing: a Inthe Specification Referencefield,typethespecificationsnameorclick to selectitfromalist.Formoreinformationaboutcreatingspecifications,see DeclaringInputandOutputParametersforaServiceonpage 122. Skiptherestofthisprocedure. Important! Whenaspecificationisassignedtoaservice,youcannotadd,delete,or modifythedeclaredvariablesusingtheservicesInput/Outputtab. 4 IfyouwanttoreferenceanISdocumenttypefortheinputoroutputparametersof theservice,dothefollowing: a IntheInputorOutputfield(dependingonwhichhalfofthespecificationyouwant toassigntheISdocumenttypeto),typetheISdocumenttypenameorclick to selectitfromalist.YoucanalsodraganISdocumenttypefromtheNavigation paneltotheboxbelowtheValidate inputorValidate outputcheckboxes. IfyouassignedanISdocumenttypetoboththeInputandOutputsidesofthe Input/Outputtab,skiptherestofthisprocedure.Otherwise,continuetothenext steptospecifythevariablesintheotherhalfofthetab. Important! WhenanISdocumenttypeisassignedtotheInputorOutputside,you cannotadd,delete,ormodifythedeclaredvariablesonthathalfoftheInput/Output tab. 5 Foreachinputoroutputvariablethatyouwanttodefine,dothefollowing: a b c Selectthehalfofthe Input/Outputtab(InputorOutput)whereyouwanttodefinethe variablebyclickinganywhereinthathalfslargewhitetextbox. Click onthetoolbarandselectthetypeofvariablethatyouwanttodefine.

TypethenameofthevariableandpressENTER.

126

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

d e

Withthevariableselected,setvariablepropertiesandapplyconstraintsinthe Propertiespanel(optional). Ifthevariableisadocumentoradocumentlist,repeatsteps bdtodefineandset thepropertiesandconstraintsforeachofitsmembers.Use memberbeneaththedocumentordocumentlistvariable. toindenteach

Ifyouwanttoenteranynotesorcommentsabouttheinputandoutputparameters, typeyourcommentsontheCommentstab.

Assigning an Output Template to a Service

AnoutputtemplateisaWebdocument,suchasanHTMLpage,embeddedwithspecial codes(tags)thatwebMethodsIntegrationServerprocesses.Thesetagsinstruct webMethodsIntegrationServertoperformaspecificactionandsubstitutetheresultof thatactionintheWebdocument.Typically,youusetagsinoutputtemplatestoinsert serviceoutputvaluesinWebdocumentsreturnedtoclients. OutputtemplatesareusedmostfrequentlytocustomizetheHTMLpagethataservice returnstoabrowserbasedapplication.However,theycanalsobeusedtogeneratean XMLdocumentoranyotherformattedstring.Forexample,youmayhaveaservicethat retrievesarecordfromarelationaldatabaseandusesanoutputtemplatetoformatitas anXMLdocumentoracommadelimitedrecordbeforereturningittotherequester. Note: Outputtemplatesareoptional.Ifaservicehasanoutputtemplateassignedtoit, theserverautomaticallyappliesthetemplatetotheresultsoftheservice(thatis,the contentsofthepipeline)wheneverthatserviceisinvokedbyanHTTPclient.Ifa servicedoesnothaveanoutputtemplate,theserversimplyreturnstheresultsofthe serviceinthebodyofanHTMLdocument,formattedasatwocolumntable. Whenusingoutputtemplates,keepinmindthat: Aservicecanhaveatmostoneoutputtemplateassignedtoitatatime(youcan dynamicallychangetheoutputtemplateassignmentatruntime,however). Youcanassignthesameoutputtemplatetomorethanoneservice. Ifyouassignanexistingoutputtemplatetoaservice,theoutputtemplatemustreside intheIntegrationServer_directory\packages\packageName\templatesdirectory,where packageNameisthepackageinwhichtheserviceislocated. Youcanreferenceoneoutputtemplatefromwithinanother. Youcanspecifytheencodinginwhichtosavethetemplate(forexample,SJIS,atype ofJapaneseencoding).TheIntegrationServerisoptimizedfortheUTF8encoding. Youshouldnotchangethissettingunlessyouaresurethatyouwanttouseanother encoding.

webMethods Developer Users Guide Version 7.1.1

127

6 Building Flow Services

To assign an output template to a service 1 2 3 Opentheservicetowhichyouwanttoassignanoutputtemplate. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheOutput templatecategoryofthePropertiespanel,dooneofthefollowingto updatetheNamefield:

Ifyouwanttoassignanewoutputtemplatetotheservice,typethenameofthe newoutputtemplateoracceptthesystemdefaultoutputtemplatenameof FolderName_ServiceName. Ifyouwanttoassignanexistingoutputtemplatetotheservice,typethefilename oftheexistingoutputtemplate.Youdonotneedtoincludethepathinformation orthefilenameextension. Important! Makesuretheexistingoutputtemplateresidesinthe IntegrationServer_directory\packages\packageName\templatesdirectory,where packageNameisthesamepackageinwhichtheserviceislocated.

IntheTypelist,dooneofthefollowingtospecifytheformatfortheoutputtemplate: To... AssignanHTMLoutputtemplatetotheservice AssignanXMLoutputtemplatetotheservice AssignaWMLoutputtemplatetotheservice AssignanHDMLoutputtemplatetotheservice Select... html xml wml hdml

Note: TheTypeyouselectdeterminestheextensionfortheoutputtemplatefile (*.html,*.xml,*.wml,or*.hdml).IncaseswheretheoutputisreturnedtoaWeb browser,theTypealsodeterminesthevalueoftheHTTPContentTypeheader field(forexample,text/html,text/xml,text/vnd.wap.wml,ortext/x hdml). 5 Dooneofthefollowing:

Ifyouassignedanewoutputtemplatetotheservice,clickNewtocreatethe outputtemplate. Ifyouassignedanexistingoutputtemplatetotheserviceandyouwanttoeditthe template,clickEdit. SelecttheencodingusedtocreatethetemplatefileandclickOK.(Bydefault, DeveloperusesUTF8tocreateoutputtemplatefiles.)

Inthetemplatedialogbox,createoredittheoutputtemplatebytypingHTML,XML, WML,orHDMLcontent,and/orbyinsertingtemplatetags.Formoreinformation

128

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

aboutcreatinganoutputtemplate,seetheDynamicServerPagesandOutputTemplates DevelopersGuide. 7 IntheFile Encodinglist,selecttheencodinginwhichyouwantthetemplatefilesaved. TheencodingisusedbytheIntegrationServertosendthetemplatetothebrowser andtointerpretdatapostedintheresultingpageinthebrowser. ThedefaultencodingisUnicode(UTF8).Youshouldnotchangethissettingunless youaresurethatyouwishtouseanotherencoding.TheIntegrationServeris optimizedfortheUTF8encoding.Theencodingyouchoosealsoappliestoany localized(translated)versionsofthetemplatethatyoumaycreate,soyoushould chooseacharacterencodingthatsupportsallofthelanguagesforwhichyouwill createlocalizedtemplates.Fordetails,seetheDynamicServerPagesandOutput TemplatesDevelopersGuide. Ifyoudochangethissetting,makesurethatyourXMLorHTMLfilecontainsthe properencodingorMETAtagfortheencodingyouuse,asthismayaffectthe browserorparserperformanceoutsidetheIntegrationServer. Note: TheFile Encodingyouselectlimitsthecharactersthatyoucanuseinyour template(includingthedatainsertedintoyourtemplateusing%VALUE% statements)tothoseinthecharactersetoftheencodingyouchoose.Italsolimits anytranslatedversionsofthetemplatestothesamecharacterset.Generallyitisa goodideatousetheUTF8(Unicode)encoding,sinceUnicodesupportsnearlyall ofthecharactersinalloftheworldslanguages.Youwillnotloseanydataifyou choosetosaveyourtemplateinUTF8;anydataenteredintoaformwillbe properlyinterpretedbytheIntegrationServer. 8 ClickSave. Important! AftereditingatemplateinDeveloper,donotedititoutsideofDeveloper. Thiswillaffecttheinterpretationoftheencodingsettingsandmayresultin charactersbeinglostormisinterpreted.

Specifying Run-Time Parameters

Asadeveloperofaservice,youcanusethePropertiespaneltospecifythefollowing serviceparameters: State of a service.Youcanmaintainwhetherornotyouwanttheservertotreatitasa statelessserviceatruntime. Caching of service results.Youcancacheelementstoreducememoryusagein Developer.Fordetails,seeTocacheelementsonpage 66. Execution locale of a service.YoucansetthetypeoflocaleinwhichtheIntegration Serverexecutesatruntime.

webMethods Developer Users Guide Version 7.1.1

129

6 Building Flow Services

Important! TheRuntimepropertiesonthePropertiespanelshouldonlybesetby someonewhoisthoroughlyfamiliarwiththestructureandoperationoftheselected service.Improperuseoftheseoptionscanleadtoaservicefailureatruntimeand/or thereturnofinvaliddatatotheclientprogram.

Maintaining the State of a Service

WhenaremoteclientopensasessiononawebMethodsIntegrationServer,theserver automaticallybuildsasessionobjectforthatclient.Theserverusesthisobjecttomaintain specificinformationabouttheclientrequestingtheservice,suchasusernameand password.Theservermaintainsthesessionobjectforthedurationofthesession(thatis, untiltheclientprogramexplicitlyclosesthesessionontheserverorthesessiontimesout duetoclientinactivity). WhenyoudevelopservicesinalanguagesuchasJava,C/C++,orVisualBasic,youcan usetheputmethodtowriteinformationtothesessionobject.Youmightdothisto storeinformationthatasequenceofservicesneedstomaintainaconnectiontoan externalsystem. Aservicethatisanatomicunitofwork(thatis,onethatiswhollyselfcontainedandnot partofamultiservicetransactiontoanexternalsystem)doesnottoneedtohaveits sessionobjectmaintainedwhenitisfinishedexecuting.Forperformancereasons,you maywanttoconfigurethesetypesofservicestoruninstatelessmode.Servicesthat runinstatelessmodeusefewerresourcesanddonotconsumealicensedseaton webMethodsIntegrationServer. Important! Donotusethestatelessoptionunlessyouarecertainthattheservice operatesasanatomicunitofwork.Ifyouareunsure,settheStatelesspropertyinthe RuntimecategorytoFalse. To configure a services run-time state 1 2 3 Opentheservicethatyouwanttoconfigure. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,dooneofthefollowingtosetthe Statelessproperty:

Iftheserviceisaselfcontained,atomicunitofworkanddoesnotneedaccessto stateinformation,selectTrue.Theserverwillremovetheclientsession immediatelyaftertheserviceexecutes,andnosessioninformationwillbe maintainedfortheservice. Iftheserviceispartofamultiservicetransactionorifyouareunsureofitsstate requirements,selectFalse.Theserverwillbuildandmaintainasessionobjectfor thisservice.

130

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Configuring a Services Use of Cache

Cachingisanoptimizationfeaturethatcanimprovetheperformanceofstatelessservices. Whenyouenablecachingforaservice,webMethodsIntegrationServersavestheentire contentsofthepipelineafterinvokingtheserviceinalocalcachefortheperiodoftime thatyouspecify.Thepipelineincludestheoutputfieldsexplicitlydefinedinthecached service,aswellasanyoutputfieldsproducedbyearlierservicesintheflow.Whenthe serverreceivessubsequentrequestsforaservicewiththesamesetofinputvalues,itreturns thecachedresulttotheclientratherthaninvokingtheserviceagain. Cachingcansignificantlyimproveresponsetimeofservices.Forexample,servicesthat retrieveinformationfrombusydatasourcessuchashightrafficcommercialWebservers couldbenefitfromcaching.Theservercancachetheresultsforflows,Javaservices,and C/C++services. Note: CachingisonlyavailablefordatathatcanbewrittentoRepositoryversion4. SincenodescannotbewrittentoRepositoryversion4,theycannotbecached.

Types of Services to Cache

Whilecachingserviceresultscanimproveperformance,notallservicesshouldbe cached.Youshouldnevercacheservicesifthecachedresultsmightbeincorrectfor subsequentinvocationsoriftheserviceperformstasksthatmustbeexecutedeachtime theserviceisinvoked.Thissectiondescribesguidelinesforyoutoconsiderwhen determiningwhethertocachetheresultsforaservice. Services Suited for Caching Services that require no state information. Ifaservicedoesnotdependonstate informationfromanearliertransactionintheclientssession,youcancacheits results. Services that retrieve data from data sources that are updated infrequently. Serviceswhose sourcesareupdatedonadaily,weekly,ormonthlybasisaregoodcandidatesfor caching. Services that are invoked frequently with the same set of inputs. Ifaserviceisfrequently invokedbyclientsusingthesameinputvalues,itisbeneficialtocachetheresults. Services that You Should Not Cache Services that perform required processing. Someservicescontainprocessingthatmustbe processedeachtimeaclientinvokesit.Forexample,ifaservicecontainsaccounting logictoperformchargebackandyoucachetheserviceresults,theserverdoesnot executetheservice,sotheservicedoesnotperformchargebackforthesubsequent invocationsoftheservice. Services that require state information.Donotcacheservicesthatrequirestate informationfromanearliertransaction,particularlyinformationthatidentifiesthe clientthatinvokedit.Forexample,youdonotwanttocacheaservicethatproduced

webMethods Developer Users Guide Version 7.1.1

131

6 Building Flow Services

apricelistforofficeequipmentifthepricesinthelistvarydependingontheclient whoinitiallyconnectstothedatasource. Services that retrieve information from frequently updated sources. Ifaserviceretrievesdata fromadatasourcethatisupdatedfrequently,thecachedresultscanbecome outdated.Donotcacheservicesthatretrieveinformationfromsourcesthatare updatedinrealtimeornearrealtime,suchasstockquotesystemsortransactional databases. Services that are invoked with unique inputs.Ifaservicehandlesalargenumberofunique inputsandveryfewrepeatedrequests,youwillgainlittlebycachingitsresults.You mightevendegradeserverperformancebyquicklyconsuminglargeamountsof memory.

Controlling a Services Use of Cache

YouusethepropertiesonthePropertiespaneltoenablecachingandtoconfiguretheway inwhichyouwantittooperatewiththeselectedservice.Youusethesesettingstostrike therightbalancebetweendatacurrencyandmemoryusage.Togaugetheeffectivenessof yourcachesettings,youcanmonitoritsperformancebyviewingservicestatisticswith theIntegrationServerAdministratorandthenadjustingyourcachingvaluesaccordingly. Note: IfyoudonothaveadministratorprivilegesonyourwebMethodsIntegration Server,workwithyourserveradministratortomonitorandevaluateyourservices useofcache. Important! Ifyoueditacachedservicebychangingtheinputs(notthepipeline),you mustresettheservercache.Ifyoudonotresetit,theoldcachedinputparameterswill beusedatruntime.ToresettheservicecachefromDeveloper,selecttheserviceand thenclicktheResetbuttonnexttoReset CacheinthePropertiespanel.Toresetthe servicecachefromIntegrationServerAdministrator,selectService UsageunderServer intheNavigationpanel.Selectthenameoftheserviceandaninformationscreenfor thatserviceappears.ClickReset Server Cache.

Specifying the Duration of a Cached Result

TheservermaintainsresultsincachefortheperiodoftimeyouspecifyintheCache expire propertyonthePropertiespanel.Theexpirationtimerbeginswhentheserverinitially cachesaresult,anditexpireswhenthetimeyouspecifyelapses.(Theserverdoesnot resettheexpirationtimereachtimeitsatisfiesaservicerequestwithacachedresult.)The minimumcacheexpirationtimeisoneminute. Note: ThecachemaynotberefreshedattheexacttimespecifiedinCache expire.Itmay varyfrom0to15seconds,accordingtothecachesweeperthread.Fordetails,seethe watt.server.cache.flushMinssettinginwebMethodsIntegrationServer.

132

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Using the Prefetch Option

YouusethePrefetchpropertytospecifywhetherornotyouwanttheserverto automaticallyrefreshthecacheforthisservicewhenitexpires.IfyousetPrefetchtoTrue, theserverautomaticallyreexecutestheservice(usingthesamesetofinputsasbefore)to updateitsresultsincache.Thisactionalsoresetsthecacheexpirationtimer. Important! UsePrefetchcarefully.Overusecanquicklyexhaustthememoryavailable forcache. Important! DonotusePrefetchwithJavaorC/C++servicesthatinvokeaccesscontrolled services.Suchserviceswillfailduringprefetchbecausetheembeddedservicewillbe invokedwithouttheproperaccessprivileges.Toavoidthisproblem,enablePrefetch ontheinvokedservicesratherthanontheJavaorC/C++servicesthatcallthem. WhenyouenablePrefetch,youmustalsosetthePrefetch activation propertytospecify whentheservershouldinitiateaprefetch.Thissettingspecifiestheminimumnumberof timesacachedresultmustbeaccessed(hit)inorderfortheservertoprefetchresults.If theserverretrievesthecachedresultsfewertimesthanspecifiedinthePrefetch activation property,theserverwillnotprefetchtheserviceresultswhenthecacheexpires. Note: Thecachemaynotberefreshedattheexacttimethelasthitfulfillsthe Prefetch activationrequirement.Itmayvaryfrom0to15seconds,accordingtothecache sweeperthread.Fordetails,seethewatt.server.cache.flushMinssettingin webMethodsIntegrationServer. To enable caching of pipeline contents after a service is invoked 1 2 3 4 5 Opentheserviceforwhichyouwanttoconfigurecaching. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,setCache resultstoTrue. IntheCache expirefield,typeanintegerrepresentingthelengthoftime(inminutes) thatyouwanttheresultsforthisservicetobeavailableincache. Ifyouwanttouseprefetch,dothefollowing: a b SetPrefetchtoTrue. InthePrefetch activationproperty,specifytheminimumnumberofhitsneededto activatetheuseofprefetch.

webMethods Developer Users Guide Version 7.1.1

133

6 Building Flow Services

Specifying the Execution Locale

Whenyoucreateaservice,youcansetthelocalepropertytoindicatethelocalepolicyin whichtheserviceexecutesatruntime.Thelocalepolicyofaservicereferstothelanguage, regional,orculturalsettingsofaspecifictargetmarket(theenduser).Eachlocaleconsists offivesections:language,extendedlanguage,script,region,andvariant. Localescaninfluencethefollowing: Stringdisplayofnumericvaluesanddate/timevalues Parsingofdatesandnumbersfromstrings Defaultcurrency(pounds,Euros,dollars) Defaultmeasuringsystem(metricorcustomary) Defaultsystemresources(suchasfonts,characterencoding,etc.) Collation(sorting)oflists Userinterface/contentlanguage TheIntegrationServerrecognizesthefollowinglocalepoliciesatruntime: Server localeusesitsdefaultJVMlocale. User locale usestheclientlocale. Root localeusesneutralorPOSIXlocale. Null localeusesnolocalepolicy. YoucanalsoenabletheIntegrationServertorecognizecustomlocales.Bydefault,the serviceusesthenulllocale.Thatis,itusesnolocalepolicy. To specify the execution locale of a service 1 2 3 Opentheservicethatyouwanttoconfigure. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,dooneofthefollowingtospecifythe Execution Localeproperty: Select... [$default] Default Runtime Locale [$user] Default User Locale [$null] No Locale Policy [root locale] [<ISO code>] <Language> Open locale editor... To... UsetheserversdefaultJVMlocale. Usetheclientlocale. Usenolocalepolicy. UsetheneutralorPOSIXlocale. Useaspecificlocale. Defineacustomlocale.

134

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

IfyouselectedOpen locale editor,completethefollowingintheDefine Custom Locale dialogbox. In this field... Language Extended Language Script Region IANA Variant Do the following... SelectoneoftheISO639codesthatrepresentthelanguage.(2 or3lettercodes) Forfuturerelease. Optional.Selectoneofthe4letterscriptcodesintheISO 15924registry. Optional.SelectoneoftheISO31662countrycodes. Optional.Addorremoveavariantcoderegisteredbythe IANA.

ClickOK.TheIntegrationServerwillexecutetheserviceinthespecifiedlocale.

Configuring Service Retry

Whenbuildingaservice,youcanconfiguretheservicetoretryautomaticallyifthe servicefailsbecauseofanISRuntimeException.AnISRuntimeExceptionoccurswhenthe servicecatchesandwrapsatransienterror,andthenrethrowsitasan ISRuntimeException.Atransienterrorisanerrorthatarisesfromatemporarycondition thatmightberesolvedorrestoredquickly,suchastheunavailabilityofaresourcedueto networkissuesorfailuretoconnecttoadatabase.Theservicemightexecutesuccessfully iftheIntegrationServerwaitsashortintervaloftimeandthenretriestheservice. Toconfigureaservicetoretry,youspecifythemaximumretryattemptsandtheretry interval.ThemaximumretryattemptsindicatehowmanyattemptstheIntegration ServermakestoreexecutetheservicewhenitendsbecauseofanISRuntimeException. Theretryintervalindicatesthelengthoftime(inmilliseconds)thattheIntegrationServer waitsbetweenexecutionattempts. Atruntime,whenaservicethrowsanISRuntimeException,theIntegrationServerwaits thelengthoftheretryintervalandthenreexecutestheserviceusingtheoriginalinput pipelinepassedtotheservice.TheIntegrationServercontinuestoretrytheserviceuntil theserviceexecutessuccessfullyortheIntegrationServermakesthemaximumnumber ofretryattempts.IftheservicethrowsanISRuntimeExceptionduringthefinalretry attempt,theIntegrationServertreatsthelastfailureasaserviceerror.Theserviceends withaserviceexception. IntegrationServergeneratesthefollowingjournallogmessagebetweenretryattempts:
[ISS.0014.0031V3] Service serviceName failed with ISRuntimeException. Retry x of y will begin in retryInterval milliseconds.

webMethods Developer Users Guide Version 7.1.1

135

6 Building Flow Services

Note: Ifserviceauditingisalsoconfiguredfortheservice,theIntegrationServeradds anentrytotheauditlogforeachfailedretryattempt.Eachoftheseentrieswillhavea statusofRetriedandanerrormessageofNull.However,iftheIntegrationServer makesthemaximumretryattemptsandtheservicestillfails,thefinalauditlogentry fortheservicewillhaveastatusofFailedandwilldisplaytheactualerrormessage.

About the Maximum Retry Period

TheIntegrationServerusesthesameserverthreadfortheinitialserviceexecutionand thesubsequentretryattempts.TheIntegrationServerreturnsthethreadtotheserver threadpoolonlywhentheserviceexecutessuccessfullyortheretryattemptsare exhausted.Topreventtheexecutionandreexecutionofasingleservicefrom monopolizingaserverthreadforalongtime,theIntegrationServerenforcesamaximum retryperiodwhenyouconfigureserviceretryproperties.Themaximumretryperiod indicatesthetotalamountoftimethatcanelapseiftheIntegrationServermakesthe maximumretryattempts.Bydefault,themaximumretryperiodis15,000milliseconds (15seconds). Whenyouconfigureserviceretry,theIntegrationSerververifiesthattheretryperiodfor thatservicewillnotexceedthemaximumretryperiod.TheIntegrationServerdetermines theretryperiodfortheservicebymultiplyingthemaximumretryattemptsbytheretry interval.Ifthisvalueexceedsthemaximumretryperiod,Developerdisplaysanerror indicatingthateitherthemaximumattemptsortheretryintervalneedstobemodified. Note: Thewatt.server.invoke.maxRetryPeriodserverparameterspecifiesthe maximumretryperiod.Tochangethemaximumretryperiod,changethevalueof thisparameter.

Setting Service Retry Properties

Whenconfiguringserviceretry,keepthefollowingpointsinmind: Youcanconfigureretryattemptsforflowservices,Javaservices,andCservicesonly. Onlytoplevelservicescanberetried.Thatis,aservicecanberetriedonlywhenitis invokeddirectlybyaclientrequest.Theservicecannotberetriedwhenitisinvoked byanotherservice(thatis,whenitisanestedservice). Ifaserviceisinvokedbyatrigger(thatis,theserviceisfunctioningasatrigger service),theIntegrationServerusesthetriggerretrypropertiesinsteadoftheservice retryproperties. Unliketriggers,youcannotconfigureaservicetoretryuntilsuccessful.

136

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

TocatchatransienterrorandrethrowitasanISRuntimeException,theservicemust dooneofthefollowing:

Iftheserviceisaflowservice,theservicemustinvoke pub.flow:throwExceptionForRetry.Formoreinformationaboutthe pub.flow:throwExceptionForRetry,seethewebMethodsIntegrationServerBuiltIn ServicesReference. IftheserviceiswritteninJava,theservicecanuse com.wm.app.b2b.server.ISRuntimeException().Formoreinformationabout constructingISRuntimeExceptionsinJavaservices,seewebMethodsIntegration ServerJavaAPIReferenceforthecom.wm.app.b2b.server.ISRuntimeException class.

Theserviceretryperiodmustbelessthanthemaximumretryperiod.Formore information,seeAbouttheMaximumRetryPeriodonpage 136. To configure service retry 1 2 3 Opentheserviceforwhichyouwanttoconfigureserviceretry. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. UndertheRetry on ISRuntimeExceptioncategoryofthePropertiespanel,intheMax attemptsproperty,specifythenumberoftimestheIntegrationServershouldattempt toreexecutetheservice.Thedefaultis0,whichindicatesthattheIntegrationServer doesnotattempttoreexecutetheservice. IntheRetry intervalproperty,specifythenumberofmillisecondstheIntegrationServer shouldwaitbetweenretryattempts.Thedefaultis0milliseconds,whichindicates thattheIntegrationServerreexecutestheserviceimmediately. OntheFilemenu,clickSave. Tip! Youcaninvokethepub.flow:getRetryCountservicetoretrievethecurrentretrycount andthemaximumspecifiedretryattempts.Formoreinformationaboutthisservice, seethewebMethodsIntegrationServerBuiltInServicesReference.Formoreinformation aboutbuildingaservicethatretries,seeConfiguringServiceRetryonpage 135.

Assigning Universal Names to Services

EveryserviceonawebMethodsIntegrationServerhasauniversalnameinadditiontoits regularwebMethodsname.Auniversalnameisauniquepublicidentifierthatexternal protocols(suchasSOAP)usetoreferenceaserviceonawebMethodsIntegrationServer. Auniversalnamehastwoparts:anamespacenameandalocalname. ThenamespacenameisaqualifierthatdistinguishesawebMethodsservicefrom otherresourcesontheInternet.Forexample,theremightbemanyresourceswiththe nameAcctInfo.AnamespacenamedistinguishesoneAcctInforesourcefromanotherby

webMethods Developer Users Guide Version 7.1.1

137

6 Building Flow Services

specifyingthenameofthecollectiontowhichitbelongs,similartothewayinwhich astateorprovincenameservestodistinguishcitieswiththesamename(forexample, Springfield,Illinois,versusSpringfield,Ontario). LikenamespacesinXML,thenamespaceportionofauniversalnameisexpressedas aURI.Thisnotationassuresuniqueness,becauseURIsarebasedongloballyunique domainnames. Thenamespaceportionoftheuniversalnamecanconsistofanycombinationof charactersthatformavalidabsoluteURI(relativeURIsarenotsupported).For example,thefollowingareallvalidnamespacenames: http://www.gsx.com http://www.gsx.com/gl/journals http://www.ugmed.ch/rsum ForacompletedescriptionofwhatmakesupavalidURI,seeRFC2396Uniform ResourceIdentifiers(URI):GenericSyntaxathttp://www.ietf.org/rfc/rfc2396.txt. Thelocalnameuniquelyidentifiesaservicewithinthecollectionencompassedbya particularnamespace.ManywebMethodsusersuseaservicesunqualifiednameas itslocalname.Underthisscheme,aservicenamedgl.journals:closeGLwouldhavea localnameofcloseGL. LocalnamesfollowthesameconstructionrulesasNCNamesinXML.Basically,a localnamecanbecomposedofanycombinationofletters,digits,orthefollowing symbols: . _ (period) (dash) (underscore)

Additionally,thelocalnamemustbeginwithaletteroranunderscore.Thefollowing areexamplesofvalidlocalnames: addCustOrder authorize_Level1 gnrent ForspecificrulesrelatingtoNCNames,seeNCNamedefinitionintheNamespaces inXMLspecificationat http://www.w3.org/TR/1999/RECxmlnames19990114. Auniversalnamecanbeeitheranexplicitoranimplicituniversalname. An explicit universal name isauniversalnamethatyouassigntoaservicebyspecifying bothanamespacenameandalocalnameinthePropertiespanel.

138

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

An implicit universal nameisautomaticallyderivedfromthenameoftheserviceitself, anditactsastheuniversalnamewhenanexplicituniversalnamehasnotbeen specified.Theserverderivesanimplicitnameasfollows:

Thenamespacenameistheliteralstringhttp://localhost/followedbythefully qualifiednameofthefolderinwhichtheserviceresidesontheIntegrationServer. Thelocalnameistheunqualifiednameoftheservice.

Fordetailsonuniversalnames,seetheSOAPDevelopersGuide. Note: TheservernormalizesuniversalnamesaccordingtoUnicodeNormalization FormC,asrecommendedbytheCharacterModel,SOAP,andXMLstandards.This ensuresthatnamescontainingnonASCIIcharacters(particularlythosewith accentedorcombiningcharacters)arerepresentedinastandardway. Forinformationaboutnormalization,seehttp://www.unicode.org/reports/tr15/ (UnicodeStandardAnnex#15)andhttp://www.w3.org/TR/charmod/(Character ModelfortheWorldWideWeb). To assign, edit, or view a universal name 1 2 3 Opentheservicewhoseuniversalnameyouwanttoassign,edit,orview. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. Ifyouwanttoassignoredittheservicesuniversalname,specifythefollowinginthe Universal NamecategoryofthePropertiespanel: In this field... Namespace name Local name Specify... TheURIthatwillbeusedtoqualifythenameofthisservice.You mustspecifyavalidabsoluteURI. Anamethatuniquelyidentifiestheservicewithinthecollection encompassedbyNamespace name.Thenamecanbecomposedof anycombinationofletters,digits,ortheperiod(.),dash()and underscore(_)characters.Additionally,itmustbeginwitha letterortheunderscorecharacter. Note: ManywebMethodsusersusetheunqualifiedportionofthe servicenameasthelocalname. 4 OntheFilemenu,clickSave. Note: Ifyoumoveaservice,orafoldercontainingaservice,Developerretainsthe servicesexplicituniversalname.Ifyoucopyaservice,orafoldercontainingaservice, Developerdoesnotretaintheservicesexplicituniversalname.

webMethods Developer Users Guide Version 7.1.1

139

6 Building Flow Services

To delete a universal name 1 2 3 4 Opentheservicewhoseuniversalnameyouwanttodelete. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheUniversal NamecategoryofthePropertiespanel,clearthesettingsinthe Namespace nameandLocal namefields. OntheFilemenu,clickSave.

Configuring Service Auditing

ServiceauditingisafeatureintheIntegrationServerthatyoucanusetotrackwhich servicesexecuted,whenservicesstartedandcompleted,andwhetherservicessucceeded orfailed.Youperformserviceauditingbyanalyzingthedatastoredintheauditlog.The auditlogcancontainentriesforservicestart,serviceend,andservicefailure.Theaudit logcanalsocontainacopyoftheinputpipelineusedtoinvoketheservice.Atruntime, servicesgenerateauditdataatpredefinedpoints.TheIntegrationServercapturesthe generatedauditdataandstoresitintheauditlog.Iftheauditlogisadatabase,youcan reinvokeservicesusingthewebMethodsMonitor. Note: WhentheIntegrationServerlogsanentryforaservice,thelogentrycontains theidentifyoftheserverthatexecutedtheservice.TheserverIDinthelogentry alwaysusestheIntegrationServerprimaryport,evenifaserviceisexecutedusing another(nonprimary)IntegrationServerport. EachservicehasasetofauditingpropertieslocatedintheAuditcategoryontheservices Propertiespanel.Thesepropertiesdeterminewhenaservicegeneratesauditdataand whatdataisstoredintheauditlog.Foreachservice,youcandecide: Whethertheserviceshouldgenerateauditdataduringexecution. Thepointsduringserviceexecutionwhentheserviceshouldgenerateauditdatato besavedintheauditlog. Whethertoincludeacopyoftheserviceinputpipelineintheauditlog. Audit properties for a service
Specifies if a service generates audit data. Specifies when to include the pipeline in the audit log.

Specifies when a service generates audit data during execution.

Keepinmindthatgeneratingauditdatacanimpactperformance.TheIntegrationServer usesthenetworktosendtheauditdatatotheauditlogandusesmemorytoactuallysave

140

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

thedataintheauditlog.Ifalargeamountofdataissaved,performancecanbeimpacted. Whenyouconfigureauditdatagenerationforservices,youshouldbalancetheneedfor auditdataagainstthepotentialperformanceimpact. Thefollowingsectionsdescribetheoptionsforgeneratingauditdataandthepotential performanceimpactofeachoption. Note: Theauditlogcanbeaflatfileoradatabase.Ifyouuseadatabase,thedatabase mustsupportJDBC.YoucanusetheIntegrationServertoviewtheauditlogwhether itisaflatfileoradatabase.Iftheauditlogisadatabase,youcanalsousethe webMethodsMonitortoviewauditdataandreinvoketheservice.Beforeyou configureserviceauditing,checkwithyourIntegrationServerAdministratortolearn whatkindofauditlogexists.Formoreinformationabouttheauditlog,seethe webMethodsLoggingGuide.

Enabling Auditing for a Service

Whenyouconfigureserviceauditing,youfirstmustdecidewhetheryouwanttobeable toaudittheservice.Thatis,doyouwanttheservicetogenerateauditdatatobecaptured intheauditlog?Ifso,youmustdecidewhethertheservicewillgenerateauditdataevery timeitexecutesoronlywhenitisinvokeddirectlybyaclientrequest(HTTP,FTP,SMTP, etc.)oratrigger. ThefollowingtabledescribeseachoptionfortheEnable auditingpropertyintheProperties panel.Keepinmindthatwheneveraservicegeneratesauditdata,performancecanbe impacted. Enable auditing option Never When top-level service only Description Theservicenevergeneratesauditdata.Selectthisoptionif youdonotwanttobeabletoauditthisservice. Theservicegeneratesauditdataonlywhenitisinvoked directlybyaclientrequestorbyatrigger.Theservicedoes notgenerateauditdatawhenitisinvokedbyanother service(thatis,whenitisanestedservice). Theservicegeneratesauditdataeverytimeitisinvoked. Selectthisoptioniftheserviceisacriticalservicethatyou wanttobeabletoauditeverytimeitexecutes.

Always

webMethods Developer Users Guide Version 7.1.1

141

6 Building Flow Services

Specifying When Audit Data Is Generated

Whenyouconfigureserviceauditing,youcanspecifythepointswhentheservice generatesauditdata.Youmightwantaservicetoproduceauditdatawhenitstarts,when itendssuccessfully,whenitfails,oracombinationofthese.UsetheoptionsintheLog on propertyonthePropertiespaneltospecifywhenaservicegeneratesauditdata. Tip! Whenaservicegeneratesauditdata,italsoproducesanauditevent.Ifyouwant theauditeventtocauseanotheractiontobeperformed,suchassendinganemail notification,writeaneventhandler.Thensubscribetheeventhandlertoauditevents. Formoreinformationabouteventsandeventhandlers,seeChapter 14,Subscribing toEvents. ThefollowingtabledescribeseachoptionintheLog onproperty.Keepinmindthatevery timetheservicegeneratesauditdata,theIntegrationServermustcapturethedataand writeittotheauditlog.Thiscandegradeperformance. Log on option Error only Description Theservicegeneratesauditdataonlywhentheserviceendsbecause ofafailure.Iftheserviceexecutessuccessfully,itwillnotgenerate auditdata. Performance Impact:Thisoptionimpactsperformanceonlywhenthe servicefails.Whenaserviceexecutessuccessfully,thisoptiondoes notimpactperformance.Thisoptionoffersthesmallestperformance impactofalltheoptionsunderLog on. Error and success Theservicegeneratesauditdatawhentheservicefinishesexecuting, regardlessofwhetheritendsbecauseofsuccessorfailure.Theaudit logwillcontainanentryforeverytimetheservicefinishesprocessing. Performance Impact:Thisoptionimpactsperformanceeverytimethe serviceexecutes,whetheritendsbecauseoferrororsuccess.Ifyou areconcernedonlywithservicesthatfail,considerusingtheError only optioninstead. Error, success, and start Theservicegeneratesauditdatawhenitbeginsexecutingandwhenit finishesexecuting.Whentheserviceexecutestocompletion,theaudit logwillcontainastartentryandanendorerrorentry. Generally,mostservicesexecutefairlyquickly.Bythetimean administratorviewstheauditlogusingwebMethodsMonitor,the auditlogwouldprobablycontainentriesforthestartandendof serviceexecution.Situationswhereyoumightwanttheserviceto generateauditdataatthestartandendofserviceexecutioninclude: Tocheckforthestartoflongrunningservices Todetectservicehangs.

142

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Log on option

Description Inbothsituations,ifserviceexecutionbeganbutdidnotcomplete,the auditlogcontainsanentryforthestartoftheservice,butnoentryfor theendoftheservice. Performance Impact:OfalltheoptionsunderLog on,thisoption providesthemostverboseandexpensivetypeofauditlogging.Every timeitexecutes,theservicegeneratesauditdataattwopoints:the beginningandtheend.TheIntegrationServermustwritetheaudit datatotheauditlogtwiceperserviceexecution.Thisrequires significantlymorediskutilizationthantheError onlyandError and successoptions.Atmost,theError onlyandError and successoptions requiretheIntegrationServertowriteauditdataonceperservice execution.

Note: Theservicegeneratesauditdataonlywhenitsatisfiestheselectedoptionunder Enable auditingandtheselectedoptionintheLog onproperty.Forexample,if When toplevel service only isselectedandtheserviceisnottherootserviceintheflowservice,it willnotgenerateauditdata.

Including the Pipeline in the Audit Log

Whenyouconfigureserviceauditing,youcanspecifywhethertheservershouldinclude acopyoftheservicesinputpipelineintheauditlog.Iftheauditlogcontainsacopyof theinputpipeline,youcanusethewebMethodsMonitortoperformmoreextensive failureanalysis,examinetheservicesinputdata,orreinvoketheservice.Usetheoptions intheInclude pipeline propertyonthePropertiespaneltospecifywhentheIntegration Servershouldsaveacopyoftheinputpipelineintheauditlog. Thepipelinedatasavedintheauditlogisthestateofthepipelinejustbeforethe invocationoftheservice.Itisnotthestateofthepipelineatthepointtheservice generatesauditdata.

webMethods Developer Users Guide Version 7.1.1

143

6 Building Flow Services

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

TheIntegrationServersavesacopyoftheinputpipelineonlyiftheservicegenerates auditdataandtheservicesatisfiestheoptionselectedintheInclude pipelineproperty.For example,ServiceAhasthefollowingsettingsonthePropertiespanel. Audit log settings for ServiceA
The audit log will contain audit and pipeline data for this service only if the service is invoked by a client or trigger and... ...the service fails.

TheauditlogwillcontaintheinputpipelineforServiceAonlyifitisthetoplevelservice (invokeddirectlybyaclientoratrigger)andtheserviceendsbecauseoffailure.If ServiceAisnotthetoplevelserviceorifServiceAexecutessuccessfully,theauditlogwill notcontainacopyoftheinputpipeline. Note: Includingthepipelineintheauditlogismorebeneficialwhentheauditlogisa database.TheIntegrationServercansavethepipelinetoaflatfileauditlog;however, youwillnotbeabletousethepipelinedatatoreinvoketheserviceorperformfailure analysis. ThefollowingtabledescribestheoptionsintheInclude pipeline propertyontheProperties panel.Keepinmindthatsavingtheinputpipelinetotheauditlogcanimpactthe performanceoftheIntegrationServer. Include pipeline Never Description TheIntegrationServerwillneversaveacopyoftheservicesinput pipelinetotheauditlog.Selectthisoptionifyouareusingaflatfile fortheauditlogorifyoudonotwanttobeabletoresubmitthe servicetotheIntegrationServer. Performance Impact:Thisoptionrequiresminimalnetworkbandwidth becausetheIntegrationServerneedstosendonlytheauditdata generatedbytheservicetotheauditlog.

144

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Include pipeline On errors only

Description TheIntegrationServersavesacopyoftheinputpipelinetotheaudit logonlywhentheservicegeneratesauditdatabecauseoffailure. Selectthisoptionifyouwanttousetheresubmissioncapabilitiesof thewebMethodsMonitortoreinvokeafailedservice.Formore informationaboutwebMethodsMonitor,seethewebMethods Monitordocumentation. Performance Impact:Forsuccessfulserviceinvocations,theOn errors only optionrequiresminimalnetworkbandwidth.Serviceinvocationsthat endinfailurerequiremorenetworkbandwidthbecausethe IntegrationServermustsavetheauditdataandtheinputpipeline. Theactualnetworkbandwidthneededdependsonthesizeofthe initialinputpipeline.Alargepipelinecandegradeperformance becauseitmaynegativelyimpacttherateatwhichthedataissavedto theauditlog.

Always

TheIntegrationServersavesacopyoftheinputpipelinetotheaudit logeverytimetheservicegeneratesauditdata.Iftheservice generatesdataatthestartandendofexecution(Log onissettoError, success, and start),theinputpipelineissavedwiththeauditlogentry forthestartofserviceexecution.Ifaservicedoesnotgenerateaudit data,theIntegrationServerdoesnotincludeacopyoftheinput pipeline. SelecttheAlwaysoptionifyouwanttobeabletousetheresubmission capabilitiesofthewebMethodsMonitortoreinvoketheservice, regardlessofwhethertheoriginalserviceinvocationsucceededor failed.Includingthepipelinecanbeusefulifaresourceexperiencesa fatalfailure(suchasharddiskfailure).Torestoretheresourcetoits prefailurestate,youcouldresubmitalltheserviceinvocationsthat occurredsincethelasttimetheresourcewasbackedup.Thisis sometimescalledafullauditforrecovery. Performance Impact:TheAlwaysoptionisthemostexpensiveoption underInclude pipeline.Thisoptionplacesthegreatestdemandon networkbandwidthbecausetheIntegrationServermustwriteacopy oftheinputpipelinetotheauditlogeverytimeaserviceexecutes. Theactualnetworkbandwidthneededdependsonthesizeofthe initialinputpipeline.Alargeinputpipelinecannegativelyimpactthe rateatwhichthedataissavedtotheauditlog.

Note: Ifyouwantauditeventsgeneratedbyaservicetopassacopyoftheinput pipelinetoanysubscribedeventhandlers,selectOn errors onlyorAlways.

webMethods Developer Users Guide Version 7.1.1

145

6 Building Flow Services

Service Auditing Use Cases

BeforeyousetpropertiesintheAuditcategoryonthePropertiespanel,decidewhattype ofauditingyouwanttoperform.Thatis,decidewhatyouwanttousetheauditlogfor. ThefollowingsectionsdescribefourtypesofauditingandidentifytheAuditproperties youwouldselecttobeabletoperformthattypeofauditing.

Error Auditing
Inerrorauditing,youusetheauditlogtotrackandreinvokefailedservices.Tousethe auditlogforerrorauditing,servicesmustgenerateauditdatawhenerrorsoccur,andthe IntegrationServermustsaveacopyoftheservicesinputpipelineintheauditlog. WithwebMethodsMonitor,youcanonlyreinvoketoplevelservices(thoseservices invokeddirectlybyaclientorbyaBroker/localtrigger).Therefore,ifyourintentwith errorauditingistoreinvokefailedservices,theserviceneedstogenerateauditdataonly whenitisthetoplevelserviceanditfails. Tomakesuretheauditlogcontainstheinformationneededtoperformerrorauditing, selectthefollowingAuditproperties. For this property... Enable auditing Select this option... When top-level service only Note: Ifyouwanttobeabletoauditallfailedinvocationsof thisservice,selectAlways. Include pipeline Log on On errors only Error only

Tousetheauditlogforerrorauditing,useadatabaseastheauditlog.

Service Auditing
Whenyouperformserviceauditing,youusetheauditlogtotrackwhichservicesexecute successfullyandwhichservicesfail.Youcanperformserviceauditingtoanalyzethe auditloganddeterminehowoftenaserviceexecutes,howmanytimesitsucceeds,and howmanytimesitfails.Tousetheauditlogforserviceauditing,servicesneedto generateauditdataafterexecutionends.

146

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Tomakesuretheauditlogcontainstheinformationneededtoperformserviceauditing, selectthefollowingAuditproperties. For this property... Enable auditing Include pipeline Select this option... When top-level service only Never Note: Configureaservicetosaveacopyoftheinput pipelineonlyifyouintendtoreinvoketheserviceusing theresubmissioncapabilitiesofthewebMethods Monitor. Log on Error and success

Tousetheauditlogforserviceauditing,youcanuseeitheraflatfileoradatabaseasthe auditlog.

Auditing for Recovery

Auditingforrecoveryinvolvesusingtheauditlogtotrackexecutedservicesandservice inputdatasothatyoucanreinvoketheservices.Youmightwanttoauditforrecoveryin theeventthataresourceexperiencesafatalfailure,andyouwanttorestoretheresource toitsprefailurestatebyresubmittingserviceinvocations. Whenauditingforrecovery,youwanttobeabletoresubmitfailedandsuccessful services.Theauditlogneedstocontainanentryforeachserviceinvokedbyaclient requestoratrigger.Theauditlogalsoneedstocontainacopyofeachservicesinput pipeline. Tousetheauditlogtoauditforrecovery,selectthefollowingAuditproperties. For this property... Enable auditing Include pipeline Log on Select this option... When top-level service only Always Error and success

Tousetheauditlogtoauditforrecovery,useadatabasefortheauditlog.

Auditing Long-Running Services

Ifaservicetakesalongtimetoprocess,youmightwanttousetheauditlogtoverifythat serviceexecutionstarted.Iftheauditlogcontainsastartentryfortheservicebutnoend orerrorentry,thenyouknowthatserviceexecutionbeganbutdidnotcomplete.To enableauditingoflongrunningservices,selecttheError, success, and startoptionforthe Log onproperty.

webMethods Developer Users Guide Version 7.1.1

147

6 Building Flow Services

Note: Typically,youwillauditlongrunningservicesinconjunctionwitherror auditing,serviceauditing,orauditingforrecovery.

Setting Auditing Options for a Service

Thefollowingprocedureexplainshowtosetauditingoptionsforaservice.Theoptions youselectdetermineifandwhenaservicegeneratesauditdata,andwhethertheaudit logincludesacopyoftheservicesinputpipeline.Makesurethatyouselectoptionsthat willprovidetheauditlogwiththeauditdatayourequire. Important! Beforeyouselectoptionsforgeneratingauditdata,checkwithyour IntegrationServerAdministratortodeterminewhatkindofauditlogexists.Anaudit logcanbeaflatfileoradatabase. To set auditing options for a service 1 Opentheserviceforwhichyouwanttoconfigureserviceauditing.Toconfigure serviceauditing,youmusthavewriteaccesstotheserviceandownthelockonthe service. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheAuditcategoryofthePropertiespanel,selectanEnable auditingoptiontoindicate whenyouwanttheservicetogenerateauditdata. FormoreinformationabouttheEnable auditingoptions,seeEnablingAuditingfora Serviceonpage 141. 4 ForInclude pipeline,selectanoptiontoindicatewhentheIntegrationServershould includeacopyoftheinputpipelineintheauditlog. Note: Ifyouwantauditeventsgeneratedbythisservicetopassacopyoftheinput pipelinetoanysubscribedeventhandlers,selectOn errors onlyorAlways. FormoreinformationabouttheInclude pipelineoptions,includinginformationabout theperformanceimpact,seeIncludingthePipelineintheAuditLogonpage 143. 5 ForLog on,selectanoptiontodeterminewhentheservicegeneratesauditdata. FormoreinformationabouttheLog onoptions,includinginformationaboutthe performanceimpact,seeSpecifyingWhenAuditDataIsGeneratedonpage 142. 6 OntheFilemenu,clickSave. Important! TheoptionsyouselectintheAuditcategoryofthePropertiespanelcanbe overwrittenatruntimebythevalueofthewatt.server.auditLogserverproperty.

2 3

148

webMethods Developer Users Guide Version 7.1.1

6 Building Flow Services

Audit Level Settings in Earlier Versions of Developer

InearlierversionsofDeveloper,youcouldconfigureauditlevelsettingsusingtheAudit levelfieldontheSettingstab.Inthisfield,youcouldselectoneofthreeauditlevelsfora service:off,brief,orverbose.BecausetheauditingoptionsonthePropertiespaneloffer morecontroloverthegenerationofauditdata,theauditlevelsettingsarenolonger available.EachoftheearlierAudit levelsettingscorrespondstoacombinationofoptions onthePropertiespanel. ThefollowingtableindicateshowtheAudit levelvaluesfromwebMethodsDeveloper4.6 (andearlier)correspondtothepropertiesonthePropertiespanel. Audit Level in Developer 4.x None Brief Verbose Enable auditing Never Always Always Include pipeline Never Never Always Log on Error, success, and start Error, success, and start

Printing a Flow Service

ThefollowingproceduredescribeshowtousetheView as HTMLcommandtoproducea printableversionofaflowservice.Thisletsyouseeallaspectsofaflow(itsinputand outputparameters,itsflowsteps,andpipelinebehavior)inasingledocument.

webMethods Developer Users Guide Version 7.1.1

149

6 Building Flow Services

A flow report lets you view all aspects of the flow service at once

Input/Output parameters

Body of the flow

Details of each flow step

To print a flow service 1 2 3 Intheeditor,selecttheservicethatyouwanttoprint. FromtheFilemenu,clickView as HTML. Ifyouwanttoprinttheflow,selectyourbrowsersprintcommand. Note: WhenyouprintaflowserviceasHTML,onlytheflowstepscurrentlyvisiblein theeditorappearintheresultingHTMLpage.Tofitallofthestepsinaflowservice intotheeditor(andtherefore,intoasingleHTMLpage),hidetheNavigation,Recent Elements,Properties,andResultspanelstomaximizetheeditor.

150

webMethods Developer Users Guide Version 7.1.1

Inserting Flow Steps

152 152 157 160 170 176 178 181 183

What Is a Flow Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting and Moving Flow Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The INVOKE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The BRANCH Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The REPEAT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SEQUENCE Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The LOOP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXIT Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The MAP Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

151

7 Inserting Flow Steps

What Is a Flow Step?

AflowstepisthebasicunitofworkthatinstructswebMethodsIntegrationServerabout whattodowithdataateachstageofaflowservice.Flowstepscaninvokeservicesand directthecourseofexecution.Usingflowstepsyoucan: Invokeaservice,suchasaflowservice,Javaservice,Cservice,orWebservice connector(INVOKE). Conditionallyexecuteonestepfromasetofspecifiedalternatives(BRANCH). Repeatasetofflowstepsuptoaspecifiednumberoftimesoruntilastepintheset failsorsucceedsasspecified(REPEAT). Groupasetofflowstepsandcontrolthewayinwhichthefailureofamemberofthe setisprocessed(SEQUENCE). Repeatasetofflowstepsovertheelementsofaspecifiedarray(LOOP). Exittheentirefloworexitasingleflowstep(EXIT). Link,add,edit,anddeletepipelinevariablesorinvokeseveralservicesthatoperate onthesamesetofpipelinevariables(MAP).

Inserting and Moving Flow Steps

Toinsertflowstepsinaflowservice,youmustopentheserviceintheeditor.Theflow stepsintheservicearelistedintheeditor.(Ifyoujustcreatedtheserviceanditdoesnot yetcontainanydefaultlogic,theeditorisempty).

152

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Displaying the steps in a flow service

Flow steps are displayed in the editor.

Note: Youmightfindithelpfultodeclaretheinputandoutputparametersforaflow servicebeforeyouinsertflowsteps.Byfirstdeclaringtheparameters,itisclearwhat datatheserviceexpectsandwhatvariablesareavailableforuseinflowsteps. Youinsertflowstepsintoaserviceusingthefollowingtoolbarbuttonsatthetopofthe editor.(Youcannotdirectlytypeaflowstepintotheeditor.Alleditingisperformed throughthetoolbar). To insert a/an... INVOKEstep MAPstep BRANCHstep LOOPstep REPEATstep Click this button... For more information, see page... 157 183 160 178 170

webMethods Developer Users Guide Version 7.1.1

153

7 Inserting Flow Steps

To insert a/an... SEQUENCEstep EXITstep

Click this button...

For more information, see page... 176 181

Note: Ifyouselectanexistingstepintheeditorbeforeinsertinganewone,Developer insertsthenewstepbelowtheonethatisselected.Ifyoudonothaveastepselected, itaddsthenewsteptotheendoftheflow.Youcanmoveasteptoanewlocation usingthearrowbuttonsonthetoolbar.Seethefollowingsection,Changingthe PositionofaFlowStep.

Changing the Position of a Flow Step

Flowstepsrunintheorderinwhichtheyappearintheeditor.Tomoveastepupor downinaflowservice,firstselectthatstepintheeditorandthenusethearrowbuttons onthetoolbartomovethestepupordowninthelist. To... Movetheflowstepupinthelist Movetheflowstepdowninthelist Youcanalsomoveaflowstepbydraggingitupordownwithyourmouseorbyusing theShiftcommandsontheComposemenu. Click this button...

Changing the Level of a Flow Step

Someflowstepshavesubordinatestepsonwhichtheyoperate.Subordinatestepsare referredtoaschildren.Forexample,whenyouusetheLOOPstep,thesetofstepsthat makeupthelooparereferredtoaschildrenofthatLOOPstep. Childrenarespecifiedbyindentingthembeneaththeirparentflowstep.Inthefollowing example,thetopLOOPstephasninechildren.NotethatoneofitschildrenisaBRANCH step,whichhasitsownsetofchildren.

154

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Child steps are indented beneath their parent step

These steps are children of the BRANCH step. This step is a child of the LOOP step.

Topromoteordemoteaflowstepwithinaparent/childhierarchy,selectthestepinthe editor,andthenuseoneofthefollowingbuttonstomoveitleftorrightbeneaththe currentparentstep. To... Demoteaflowstepinthehierarchy(thatis,maketheselectedstepa childoftheprecedingparentstep) Thisbuttonwillonlybeavailableifyouselectastepthatcan becomeachild. Promoteaflowstepinthehierarchy(thatis,movethesteponelevel upinthehierarchy) Click this button...

webMethods Developer Users Guide Version 7.1.1

155

7 Inserting Flow Steps

Setting the Properties of a Flow Step

Everyflowstepisassociatedwithauniquesetofproperties.Thepropertiesforaflow steparedisplayedinthePropertiespanel.ValuesthatyouspecifyinthePropertiespanel applyonlytotheselectedstepintheeditor. Properties of a flow step

Use the Properties panel to view and set the properties of a flow step.

Althougheachtypeofflowstephasasetofuniqueproperties,theyallhavethe followingproperties: Property Description

Comments Assignsanoptionaldescriptivecommenttotheselectedflowstep. Label Assignsanametotheselectedflowstep.Whenalabelisassigned,that labelappearsnexttothestepintheeditor.Thelabelallowsyouto referencethatflowstepinotherflowsteps.Inaddition,youusethelabel tocontrolthebehaviorofcertainflowsteps.Forexample,theBRANCH stepusestheLabelpropertytodeterminewhichalternativeitissupposed toexecute. SeeTheBRANCHSteponpage 160andTheEXITSteponpage 181 foradditionalinformationaboutthisuseofthelabelproperty. Foracompletedescriptionofthepropertiesassociatedwitheachflowstep,see Appendix A,webMethodsFlowSteps.

156

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

The INVOKE Step

UsetheINVOKEsteptorequestaservicewithinaflow.YoucanusetheINVOKEstepto: Invokeanytypeofservice,includingotherflowservicesandWebserviceconnectors. Invokeanyserviceforwhichthecallerofthecurrentflowhasaccessrightsonthe localwebMethodsIntegrationServer. InvokebuiltinservicesandservicesonotherwebMethodsIntegrationServers. Invokeflowservicesrecursively(thatis,aflowservicethatcallsitself).Ifyouusea flowservicerecursively,bearinmindthatyoumustprovideameanstoendthe recursion. Invokeanyservice,validatingitsinputand/oroutput.Fordetails,seePerforming Input/OutputValidationonpage 259. Flow service containing INVOKE steps

Specifying the Service Property

TheINVOKEstepsServicepropertyspecifieswhichservicewillbeinvokedatruntime. WhenyouinsertanINVOKEstep,Developerautomaticallyassignsthenameofthat servicetotheServiceproperty. IfyouwanttochangetheserviceassignedtoanINVOKEstep,youedittheService property.Youeditthispropertyinoneoftwoways: ByclickingtheServicepropertyseditbutton( )andselectingaservicefromthe Selectdialogbox.Thisisthepreferredmethod. BytypingthenameofaserviceintheServicetextbox.Whenyouspecifyaservicein thismanner,keepthefollowingpointsinmind:

YoumustspecifytheservicesfullyqualifiednameinfolderName:serviceName format. Examplepurchasing.orders:getOrders

Youmustspecifytheservicesnameexactlyasitisdefinedontheserver.Service namesarecasesensitive.

webMethods Developer Users Guide Version 7.1.1

157

7 Inserting Flow Steps

Invoking a Built-In Service

Thereisanextensivesetofbuiltinservicesthatyoucaninvokefromaflowservice.The webMethodslibraryincludesservicesfordoingsuchthingsastransformingdatavalues, performingsimplemathematicaloperations,extractinginformationfromXML documents,andaccessingdatabases. BuiltinservicesresideintheWmPublicpackage.Foracompletedescriptionofthese services,seethewebMethodsIntegrationServerBuiltInServicesReference. Note: Ifyouareusinganyadapters(forexample,thewebMethodsJDBCAdapter), youwillhaveadditionalbuiltinservices,whichareprovidedbytheadapters.Seethe documentationprovidedwiththoseadaptersfordetails.

Invoking a Service on Another webMethods Integration Server

Youcanusethebuiltinservicepub.remote:invoketoinvokeaserviceonaremote IntegrationServerandreturntheresults.Theremoteserverisidentifiedbyanalias, whichisconfiguredontheRemote ServersscreenintheIntegrationServerAdministrator. Thepub.remote:invoke serviceautomaticallyhandlesopeningasessionandauthentication ontheremoteserver. Thepub.remote:invokeserviceresidesintheWmPublicpackageandrequiresthealiasofthe remoteserverandthefullyqualifiednameoftheservicethatyouwanttoinvokeas input.Foracompletedescriptionofthisservice,seethewebMethodsIntegrationServer BuiltInServicesReference.

Building an INVOKE Step

Usethefollowingproceduretoinvokeaservicewithinaflowservice. To build an INVOKE step 1 2 Opentheflowserviceinwhichyouwanttoinvokeanotherservice.Intheeditor, selectthestepimmediatelyabovewhichyouwanttoinserttheINVOKEstep. Click ontheeditortoolbarandthenselecttheserviceyouwanttoinvoke.Ifthe serviceyouwanttoinvokedoesnotappearinthelist,clickBrowsetonavigatetoand selecttheservice. Tip! Youcanalsoaddinvokestepsbyselectingoneormoreservicesinthe Navigationpanelanddraggingthemtothedesiredpositionwithintheflowin theeditor.Theservicesmustresideonthesameserverastheflowservice.

158

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

CompletethefollowingfieldsonthePropertiespanel: For this property... Service Specify... Thefullyqualifiednameoftheservicethatwillbeinvokedatrun time.Whenyouinsertaservice,Developerautomaticallyassigns thenameofthatservicetotheServiceproperty.Ifyouwantto changetheservicethatisinvoked,specifytheservicesfully qualifiednameintheformatfolderName:serviceNameorclick andselectaservicefromthelist. Optional.Specifiesthemaximumnumberofsecondsthatthis stepshouldrun.Ifthistimeelapsesbeforethestepcompletes,the serverwaitsforthesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols.For example,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank. Validate input Whetherornotyouwanttheservertovalidatetheinputtothe serviceagainsttheserviceinputsignature.SelectTrue tovalidate theinput.SelectFalse ifyoudonotwanttovalidatetheinput. Forinformationaboutvalidatinginput,seePerforming Input/OutputValidationonpage 259. Validate output Whetherornotyouwanttheservertovalidatetheoutputofthe serviceagainsttheserviceoutputsignature.SelectTruetovalidate theoutput.SelectFalseifyoudonotwanttovalidatetheoutput. Forinformationaboutvalidatingoutput,seePerforming Input/OutputValidationonpage 259.

Timeout

Ifnecessary,onthePipelinetab,linkPipeline InvariablestoService Invariables.Link Service OutvariablestoPipeline Outvariables.Formoreinformationaboutlinking variablestoaservice,seeLinkingVariablesonpage 192. Tip! WhenyouinstallDeveloper,the Insertmenudisplaysalistofcommonly usedservices.YoucanusetheToolsOptionscommandtocustomizethislistof servicestosuityourneeds.

webMethods Developer Users Guide Version 7.1.1

159

7 Inserting Flow Steps

The BRANCH Step

TheBRANCHstepallowsyoutoconditionallyexecuteastepbasedonthevalueofa variableatruntime.Forexample,youmightuseaBRANCHsteptoprocessapurchase orderonewayifthePaymentTypevalueisCREDITCARDandanotherwayifitis CORPACCT. WhenyoubuildaBRANCHstep,youcan: Branch on a switch value.Useavariabletodeterminewhichchildstepexecutes.Atrun time,theBRANCHstepmatchesthevalueoftheswitchvariabletotheLabelproperty ofeachofitstargets.Itexecutesthechildstepwhoselabelmatchesthevalueofthe switch. Branch on an expression.Useanexpressiontodeterminewhichchildstepexecutes.At runtime,theBRANCHstepevaluatestheexpressionintheLabelpropertyofeach childstep.Itexecutesthefirstchildstepwhoseexpressionevaluatestotrue. Important! Youcannotbranchonaswitchvalueandanexpressionforthesame BRANCHstep.Ifyouwanttobranchonthevalueofasinglevariableandyouknow thepossibleruntimevaluesoftheswitchvariableexactly,branchontheswitchvalue. Ifyouwanttobranchonthevaluesofmorethanonevariableoronarangeofvalues, branchonexpressions.

Branching on a Switch Value

Whenyoubranchonaswitchvalue,youbranchonthevalueofasinglevariableinthe pipeline. To branch on a switch value 1 2 Createalistoftheconditionalsteps(targetsteps)andmakethemchildrenofthe BRANCHstep. InthePropertiespanelfortheBRANCHstep,specifyintheSwitchpropertythename ofthepipelinevariablewhosevaluewillactastheswitch.Formoreinformation aboutthisproperty,seeSpecifyingtheSwitchVariableonpage 161. IntheLabelpropertyofeachtargetstep,specifythevaluethatwillcausethatstepto execute.Formoreinformationaboutthisproperty,seeSpecifyingtheLabelValue onpage 161.

160

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Simple BRANCH step that branches on a switch value

Each conditional step has a label that matches the value that causes it to execute.

The switch property of the BRANCH step specifies the name of the variable that acts

Specifying the Switch Variable

Thevariableyouuseastheswitchvariable: MustbeaStringorconstrainedObjectvariable. MustbeavariablethatcanexistinthepipelinewhentheBRANCHstepisexecuted atruntime. Mustbeformattedasdocument/documentVariable,ifyouarespecifyingafieldina documentastheswitchvariable(forexample,BuyerInfo/AccountNum).

Specifying the Label Value

Atruntime,theBRANCHstepcomparesthevalueoftheswitchvariabletotheLabel propertyofeachofitstargets.Itexecutesthetargetstepwhoselabelmatchesthevalueof theswitchvariable. YoucanusearegularexpressiontospecifythematchingvalueforaBRANCHstep.Todo so,usethefollowingsyntaxtospecifythevalueinLabel: /RegularExpression/ Forexample,ifyouwanttoselectastepbasedonwhetheraPOnumberstartswiththe stringRELyouuse/^REL/asthevalueofLabel.Formoreinformationaboutregular expressions,seeAppendix B,RegularExpressions. Unlikeotherflowstepswhosechildrenexecuteinsequenceatruntime,onlyonechildof aBRANCHstepisexecuted:thetargetwhoselabelmatchesthevalueoftheswitch variable.Ifnoneofthetargetsmatchtheswitchvariable,noneofthemareperformed, andexecutionfallsthroughtothenextstepintheflowservice.Forexample,inthe followingflowservice,executionpassesdirectlytotheLogTransactionserviceifthevalueof PaymentTypeisCOD.

webMethods Developer Users Guide Version 7.1.1

161

7 Inserting Flow Steps

An unmatched value will fall though the BRANCH

If PaymentType is COD, execution will fall through this BRANCH step.

KeepthefollowingpointsinmindwhenassigninglabelstothetargetsoftheBRANCH step: Youmustgiveeachtargetstepalabelunlessyouwanttomatchanemptystring.For thatcase,youleavetheLabelpropertyblank.Formoreaboutmatchinganempty string,seeBranchingonNullandEmptyValuesonpage 164. EachLabelvaluemustbeuniquewithintheBRANCHstep. WhenyouspecifyaliteralvalueastheLabelofachildstep,thevalueyouspecify mustmatchtheruntimevalueoftheswitchvariableexactly.TheLabelpropertyis casesensitive. YoucanusearegularexpressionasthevalueofLabelinsteadofaliteralvalue. Youcanmatchanullvaluebyusingthe$nullvalueintheLabelproperty.Formore informationaboutspecifyinganullvalue,seeBranchingonNullandEmptyValues onpage 164. Youcandesignateadefaultstepforallunmatchedcasesbyusingthe$defaultvaluein theLabelproperty.Formoreinformationaboutusingthe$defaultsetting,Specifying aDefaultSteponpage 165.

162

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Branching on an Expression
Whenyoubranchonanexpression,youassignanexpressiontoeachchildofabranch step.Atruntime,theBRANCHstepevaluatestheexpressionsassignedtothechild steps.Itexecutesthefirstchildstepwithanexpressionthatevaluatestotrue. To branch on an expression 1 2 3 Createalistoftheconditionalsteps(targetsteps)andmakethemchildrenofthe BRANCHstep. InthePropertiespanelfortheBRANCHstep,setEvaluate labelstoTrue. IntheLabelpropertyofeachtarget,specifytheexpressionthat,whentrue,willcause thetargetsteptoexecute.Theexpressionsyoucreatecanincludemultiplevariables andcanspecifyarangeofvaluesforvariables.Usethesyntaxprovidedby webMethodstocreatetheexpression.Formoreinformationaboutexpressionsyntax, seeAppendix D,ConditionalExpressions.

Simple BRANCH step that branches on an expression

Each target step has an expression as the label.

When set to true, the Evaluate labels property indicates the step branches on expressions.

KeepinmindthatonlyonechildofaBRANCHstepisexecuted:thefirsttargetstep whoselabelcontainsanexpressionthatevaluatestotrue.Ifnoneoftheexpressions evaluatetotrue,noneofthechildstepsareinvoked,andexecutionfallsthroughtothe nextstepintheflowservice.Youcanusethe$defaultvalueintheLabelpropertyto designateadefaultstepforcaseswherenoexpressionsevaluatetotrue.Formore informationaboutusingthe$default value,seeSpecifyingaDefaultSteponpage 165. Important! TheexpressionsyoucreateforthechildrenofaBRANCHstepneedtobe mutuallyexclusive(onlyoneconditionshouldevaluatetotrueatruntime).

webMethods Developer Users Guide Version 7.1.1

163

7 Inserting Flow Steps

Branching on Null and Empty Values

WhenyoubuildaBRANCHstep,youcanincludetargetstepsthatmatchnullorempty switchvalues.TheBRANCHstepconsidersaswitchvaluetobenullifthevariabledoes notexistinthepipelineorisexplicitlysettonull.TheBRANCHstepconsidersaswitch valuetobeanemptystringifthevariableexistsinthepipelinebutitsvalueisazero lengthstring.Tobranchonnulloremptyvalues,settheLabelpropertyforthetargetstep asfollows. To BRANCH on... Anullvalue Do the following... SettheLabelpropertyto$null.Atruntime,theBRANCHstep executesthetargetstepwiththe$nulllabeliftheswitchvariableis explicitlysettonullordoesnotexistinthepipeline. Youcanuse$nullwithanytypeofswitchvariable. Anempty string LeavetheLabelpropertyblank(empty).Atruntime,theBRANCH stepexecutesthetargetstepwithnolabeliftheswitchvariableis present,butcontainsnocharacters. Youcanuseanemptyvalueonlywhentheswitchvariableisoftype String. Important! Ifyoubranchonexpressions(Evaluate labelsissettoTrue),youcannot branchonnulloremptyvalues.WhenexecutingtheBRANCHstepandevaluating labels,theserverignorestargetstepswithablankor$nulllabel. ThefollowingexampleshowsaBRANCHstepusedtoauthorizeacreditcardnumber basedonthebuyerscreditcardtype(CreditCardType).Itcontainsthreetargetsteps.The firsttargetstephandlessituationswherethevalueofCreditCardTypeisnullorwhere CreditCardTypedoesnotexistinthepipeline.Thesecondtargetstephandlescaseswhere thevalueofCreditCardTypeisanemptystring.(Notethatthefirsttwotargetstepsare EXITstepsthatwillreturnafailureconditionwhenexecuted.)Thethirdtargetstephas the$defaultlabel,andwillprocessallspecifiedcreditcardtypes.

164

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

BRANCH that contains target steps to match null values or empty strings

This target step executes when CreditCardType is null or does not exist.

This target step executes when the CreditCardType value is a zero length string.

Specifying a Default Step

IfyouwanttopreventtheservicefromfallingthroughaBRANCHstepwhenan unmatchedvalueoccursatruntime,includeadefaulttargetsteptohandleunmatched cases.TospecifythedefaultalternativeofaBRANCHstep,settheLabelpropertyto $default. ThefollowingexampleshowsaBRANCHstepthatisusedtoauthenticatepaymentfor anorderbasedonthetypeofpayment(PaymentType).Itcontainsthreetargetsteps.The firsttargetstephandlesorderspaidforbyCreditCard.Thesecondtargetstephandles orderspaidforthroughaCorporateAccount.Thethirdtargetstephasthe$defaultlabel andwillprocessallotherpaymenttypes.

webMethods Developer Users Guide Version 7.1.1

165

7 Inserting Flow Steps

The default step is set to $default

The first two target steps handle credit card and corporate account payments... ...and the $default target step handles the rest.

Important! YoucanonlyhaveonedefaulttargetstepforaBRANCHstep.Developer alwaysevaluatesthedefaultsteplast.Thedefaultstepdoesnotneedtobethelast childoftheBRANCHstep.

Using SEQUENCE as the Target of a BRANCH

Inmanycases,youmaywantaBRANCHsteptoconditionallyexecuteaseriesof multiplestepsratherthanjustasinglestep.Forthesecases,youcanusetheSEQUENCE stepasthetargetstepandgroupaseriesofflowstepsbeneathit. Thefollowingexampleillustratesaservicethatacceptsapurchaseorderandprocessesit oneofthreewaysdependingonthepaymenttypespecifiedinthePaymentTypevariable. BecauseaseriesofstepsareneededtoprocessthePOineachcase,thetargetsofthe BRANCHaredefinedasSEQUENCEsteps,andtheappropriateseriesofstepsare specifiedaschildrenbeneatheachSEQUENCE.

166

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

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.

TheSEQUENCEstepthatyouuseasatargetforaBRANCHcancontainanyvalidflow step,includingadditionalBRANCHsteps.Foradditionalinformationaboutbuildinga SEQUENCE,seeTheSEQUENCESteponpage 176.

webMethods Developer Users Guide Version 7.1.1

167

7 Inserting Flow Steps

Building a BRANCH Step

UsethefollowingproceduretobuildaBRANCHstepinaflowservice. To build a BRANCH step 1 IfyouareinsertingaBRANCHstepintoanexistingflowservice,displaythatservice intheeditorandhighlightthestepimmediatelyabovewhereyouwanttheBRANCH stepinserted. Click ontheeditortoolbar.

2 3

CompletethefollowingfieldsonthePropertiespanel: For this property... Comments Scope Specify... Anoptionaldescriptivecommentforthisstep. Thenameofadocument(IDataobject)inthepipelinetowhich youwanttorestrictthisstep.Ifyouwantthissteptohaveaccess totheentirepipeline,leavethispropertyblank. Themaximumnumberofsecondsthatthisstepshouldrun.If thistimeelapsesbeforethestepcompletes,theserverwaitsfor thesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank. Label Anoptionalnameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank).Formoreinformationabout branchingonnulloremptyvalues,seeBranchingonNulland EmptyValuesonpage 164. Note: IfyouusethisstepasatargetforanotherBRANCHoran EXITstep,youmustspecifyavalueintheLabelproperty.For moreinformationabouttheEXITstep,seeTheEXITStepon page 181. Switch ThenameoftheStringorconstrainedObjectvariablewhose valuewillbeusedtodeterminewhichchildsteptoexecuteatrun time.DonotspecifyaswitchvariableifyousettheEvaluate labels propertytoTrue.

Timeout

168

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

For this property... Evaluate labels

Specify... Whetherornotyouwanttoevaluatelabelsofchildstepsas conditionalexpressions.SelectTruetobranchonexpressions. SelectFalse(thedefault)ifyouwanttobranchontheswitch value.

InserttheconditionalstepsthatbelongtotheBRANCH(thatis,itschildren)using thefollowingsteps: a b c Insertaflowstepusingthebuttonsontheeditortoolbar. Indenttheflowstepusing BRANCHstep. ontheeditortoolbartomakeitachildofthe

IntheLabelpropertyonthePropertiespanel,specifytheswitchvaluethatwill causethissteptoexecuteatruntime. To match... Thatexactstring TheStringrepresentationoftheobjectsvalue Example for Boolean objecttrue Example for Integer object123 Anystringfittingthecriteriaspecifiedbytheregular expression Example/^REL/ Anemptystring Anullvalue Anyunmatchedvalue(thatis,executethestepifthevalue doesnotmatchanyotherlabel) Ablankfield $null $default Aregular expression Specify... Astring Aconstrained objectvalue

Setotherpropertiesasneeded.

Important! Ifyouarebranchingonexpressions,makesuretheexpressionsyouassign tothetargetstepsaremutuallyexclusive.Inaddition,donotusenulloremptyvalues aslabelswhenbranchingonexpressions.TheBRANCHstepignorestargetsteps witha$nulllabelorblanklabel.

webMethods Developer Users Guide Version 7.1.1

169

7 Inserting Flow Steps

The REPEAT Step

TheREPEATstepallowsyoutoconditionallyrepeatasequenceofchildstepsbasedon thesuccessorfailureofthosesteps.YoucanuseREPEATto: Re-execute (retry) a set of steps if any step within the set fails.Thisoptionisusefulto accommodatetransientfailuresthatmightoccurwhenaccessinganexternalsystem (forexample,databases,ERPsystems,Webservers,orWebservices)ordevice. Re-execute a set of steps until one of the steps within the set fails.Thisoptionisusefulfor repeatingaprocessaslongasaparticularsetofcircumstancesexists(forexample, dataitemsexistinadataset). Use REPEAT to re-execute one or more steps

This INVOKE step is repeated up to 10 times if it fails at run time.

Specifying the REPEAT Condition

WhenyoubuildaREPEATstep,yousettheRepeat onpropertytospecifythecondition (successorfailure)thatwillcauseitschildrentoreexecuteatruntime. If you set Repeat on to FAILURE SUCCESS The REPEAT step Reexecutesthesetofchildstepsifanystepinthesetfails. Reexecutesthesetofchildstepsifallstepsintheset completesuccessfully.

170

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Setting the REPEAT Counter

TheREPEATstepsCountpropertyspecifiesthemaximumnumberoftimestheserverre executesthechildstepsintheREPEATstep. If you set Count to 0 Any value > 0 -1 or blank The REPEAT step Doesnotreexecutechildren. Reexecuteschildrenuptothisnumberoftimes. ReexecuteschildrenaslongasthespecifiedRepeat on conditionistrue.

Important! NotethatchildrenofaREPEATalwaysexecuteatleastonce.TheCount propertyspecifiesthemaximumnumberoftimesthechildrencanbereexecuted.At theendofaniteration,theservercheckstoseewhetherthecondition(thatis,failure orsuccess)forrepeatingissatisfied.IftheconditionistrueandtheCountisnotmet, thechildrenareexecutedagain.Thisprocesscontinuesuntiltherepeatconditionis falseorCountismet,whicheveroccursfirst.(Inotherwords,themaximumnumberof timesthatchildrenofaREPEATwillexecutewhenCountis>1,isCount+1.)

When Does REPEAT Fail?

ThefollowingconditionscausetheREPEATsteptofail: If Repeat on is set to SUCCESS FAILURE The REPEAT step fails if AchildwithintheREPEATblockfails. TheCountlimitisreachedbeforeitschildrenexecute successfully.

IftheREPEATstepisachildofanotherflowstep,thefailureispropagatedtoitsparent.

Using REPEAT to Retry a Failed Step

Ifyourflowinvokesservicesthataccessexternalsystems,youcanusetheREPEATstep toaccommodatenetworkerrors,suchasbusyserversorconnectionerrors,atruntime.If youusetheREPEATstepforthispurpose,keepthefollowingpointsinmind: ThefollowingtypesoffailuressatisfytheFAILUREcondition:

ExpirationofachildstepsTimeoutlimit AnexceptionthrownbyaJavaservice Adocumentquerythatreturnsanunpermittednullvalue

webMethods Developer Users Guide Version 7.1.1

171

7 Inserting Flow Steps

IfyouspecifymultiplechildrenunderaREPEATstep,thefailureofanyoneofthe childrenwillcausetheentiresetofchildrentobereexecuted. TheREPEATstepimmediatelyexitsasetofchildrenatthepointoffailure(thatis,if thesecondchildinasetofthreefails,thethirdchildisnotexecuted). WhenRepeat onissettoFAILURE,thefailureofachildwithinaREPEATstepdoes notcausetheREPEATstepitselftofailunlesstheCountlimitisalsoreached. TheTimeoutpropertyfortheREPEATstepspecifiestheamountoftimeinwhichthe entireREPEATstep,includingallofitspossibleiterations,mustcomplete.Whenyou useREPEATtoretryonfailure,youmaywanttoleavetheTimeoutvalueat0(nolimit) orsetittoaveryhighvalue.Youcanalsosetthepropertytothevalueofapipeline variablebytypingthenameofthevariablebetween%symbols. Asadeveloper,youmustbethoroughlyfamiliarwiththeprocessesyouinclude withinaREPEATstep.Makecertainthatthechildstepsyouspecifycansafelybe repeatedintheeventthatafailureoccurs.YoudontwanttouseREPEATifthereis thepossibilitythatasingleaction,suchasacceptinganorderorcreditinganaccount balance,couldbeappliedtwice. To build a REPEAT step that re-executes failed steps 1 IfyouareinsertingaREPEATstepintoanexistingflowservice,displaythatservice intheeditorandhighlightthestepimmediatelyabovewhereyouwanttheREPEAT stepinserted. Click ontheeditortoolbar.

2 3

CompletethefollowingfieldsonthePropertiespanel: For this property... Comments Scope Specify... Anoptionaldescriptivecommentforthisstep. Thenameofadocument(IDataobject)inthepipelineto whichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Themaximumnumberofsecondsthatthisstepshouldrun.If thistimeelapsesbeforethestepcompletes,theserverwaitsfor thesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank.

Timeout

172

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

For this property... Label

Specify... AnoptionalnameforthisspecificREPEATstep,oranull, unmatched,oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHor EXITstep,youmustspecifyavalueintheLabelproperty.For moreinformationabouttheBRANCHandEXITsteps,see TheBRANCHSteponpage 160orTheEXITStepon page 181.

Count

Themaximumnumberoftimesyouwantthechildrentobe reexecuted.Ifyouwanttousethevalueofapipelinevariable forthisproperty,typethevariablenamebetween%symbols (forexample,%servicecount%). Ifyouwantthechildrenreexecuteduntiltheyareall successful(thatis,nomaximumlimit),setthisvalueto1.

Repeat interval

Thelengthoftime(inseconds)thatyouwanttheserverto waitbetweeniterationsofthechildren. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%waittime%).

Repeat on 4

FAILURE

BeneaththeREPEATstep,usethefollowingstepstoinserteachstepthatyouwantto repeat: a b c Insertaflowstepusingthebuttonsontheeditortoolbar. Indentthatflowstepusing REPEATstep.) ontheeditortoolbar.(Makeitachildofthe

Setthepropertiesforthechildstepasneeded.

webMethods Developer Users Guide Version 7.1.1

173

7 Inserting Flow Steps

Using REPEAT to Retry a Successful Step

ApartfromusingREPEATtoretryafailedstep,youcanalsouseitasaloopingdeviceto repeataseriesofstepsuntilafailureoccurs. IfyouusetheREPEATsteptoreexecutesuccessfulchildsteps,keepthefollowingpoints inmind: ThesuccessconditionismetifallchildrenoftheREPEATstepexecutewithout returningasingleexception. Ifonechildinthesetfails,theREPEATstepexitsatthepointoffailure,leavingthe remainingchildrenunexecuted. ThefailureofachilddoesnotcausetheREPEATsteptofail;itmerelyendstheloop. (Inthiscase,theREPEATstepitselfsucceedsandexecutionoftheflowproceeds normally). To build a REPEAT step that repeats a set of successful steps 1 IfyouareinsertingaREPEATstepintoanexistingflowservice,displaythatservice intheeditorandhighlightthestepimmediatelyabovewhereyouwanttheREPEAT stepinserted. Click ontheeditortoolbar.

2 3

CompletethefollowingfieldsonthePropertiespanel: For this property... Comments Scope Specify... Anoptionaldescriptivecommentforthisstep. Thenameofadocument(IDataobject)inthepipelineto whichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Themaximumnumberofsecondsthatthisstepshouldrun.If thistimeelapsesbeforethestepcompletes,theserverwaitsfor thesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank.

Timeout

174

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

For this property... Label

Specify... Anoptionalnameforthisspecificstep,oranull,unmatched, oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHor EXITstep,youmustspecifyavalueinthelabelproperty.For moreinformationabouttheBRANCHandEXITsteps,see TheBRANCHSteponpage 160orTheEXITStepon page 181.

Count

Themaximumnumberoftimesyouwantthechildrentobe reexecuted.Ifyouwanttousethevalueofapipelinevariable forthisproperty,typethevariablenamebetween%symbols (forexample,%servicecount%). Ifyouwantthechildrenreexecuteduntilanyoneofthem fails(thatis,nomaximumlimit),setthisvalueto1.

Repeat interval

Thelengthoftime(inseconds)thatyouwanttheserverto waitbetweeniterationsofthechildren. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%waittime%).

Repeat on 4

SUCCESS

BeneaththeREPEATstep,usethefollowingstepstoinserteachstepthatyouwant repeat: a b c Insertaflowstepusingthebuttonsontheeditortoolbar. Indentthatflowstepusing REPEATstep. ontheeditortoolbartomakeitachildofthe

Setthepropertiesforthechildstepasneeded.

webMethods Developer Users Guide Version 7.1.1

175

7 Inserting Flow Steps

The SEQUENCE Step

YouusetheSEQUENCEsteptobuildasetofstepsthatyouwanttotreatasagroup. Stepsinagroupareexecutedinorder,oneafteranother.Bydefault,allstepsinaflow service,exceptforchildrenofaBRANCHstep,areexecutedasthoughtheywere membersofanimplicitSEQUENCEstep(thatis,theyexecuteinorder,oneafter another).However,therearetimeswhenitisusefultoexplicitlygroupasetofsteps.The mostcommonreasonstodothisare: TogroupasetofstepsasasinglealternativebeneathaBRANCHstep.Fordetails aboutthisuseoftheSEQUENCEstep,seeUsingSEQUENCEastheTargetofa BRANCHonpage 166. Tospecifytheconditionsunderwhichtheserverwillexitasequenceofstepswithout executingtheentireset.

Using SEQUENCE to Specify an Exit Condition

Inanimplicitsequence,whenastepfails,theserverautomaticallyexitsthesequence (thatis,theExit onpropertyissettoFAILURE).Bygroupingstepsintoanexplicitsequence, youcanoverridethisdefaultbehaviorandspecifytheconditiononwhichthesequence exits.Todothis,yousettheExit onparameterasfollows: If you want the server to Exitthesequencewhenastepinthesequencefails.(Execution continueswiththenextflowstepintheflowservice.)Thisisthe defaultbehaviorofasequenceofsteps. Thissettingisusefulifyouhaveaseriesofstepsthatbuildupon oneanother.Forexample,ifyouhaveasetofstepsthatgetsan authorizationcodeandthensubmitsaPO,youwillwanttoskipthe POsubmissioniftheauthorizationstepfails. WhenaSEQUENCEexitsunderthiscondition,theSEQUENCE stepfails. Note: WhenaSEQUENCEstepexitsonfailure,theIntegration Serverrollsbackthepipelinecontents.Thatis,theIntegration Serverreturnsthepipelinetothestateitwasinbeforethe SEQUENCEstepexecuted. Set Exit on to FAILURE

176

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

If you want the server to Exitthesequencewhenanystepinthesequencesucceeds. (Executioncontinueswiththenextstepintheflowservice.) Thissettingisusefulforbuildingasetofalternativestepsthatare eachattemptedatruntime.Onceoneofthemembersofthesetruns successfully,theremainingstepsinthesequenceareskipped. WhenaSEQUENCEexitsunderthiscondition,theserverconsiders theSEQUENCEstepsuccessful,evenifallitschildrenfail.Ifachild failsunderthiscondition,anychangesthatitmadetothepipeline arerolledback(undone),andprocessingcontinueswiththenext childstepintheSEQUENCE. Executeeverystepinthesequenceevenifoneofthestepsinthe sequencefails. TheserverconsidersaSEQUENCEstepsuccessfulaslongasit executesallofitschildrenwithinthespecifiedtimeoutlimit.The successorfailureofachildwithinthesequenceisnottakeninto consideration.Ifachildfailsunderthiscondition,anychangesthat itmadetothepipelinearerolledback(undone),andprocessing continueswiththenextchildstepintheSEQUENCE.

Set Exit on to SUCCESS

DONE

Note: Rollbackoperationsareperformedonthefirstlevelofthepipelineonly.Thatis, firstlevelvariablesarerestoredtotheiroriginalvaluesbeforethestepfailed,butthe serverdoesnotrollbackchangestoanydocumentstowhichthefirstlevelvariables refer. Note: AfailureinaMAPstep(thatis,afailureinoneofthetransformers)willcause thecontainingSEQUENCEtoexitwhenyousetExit ontoFAILURE.However,aMAP stepthatdoesnotfailwillnotcausethecontainingSEQUENCEtoexitwhenyouset Exit ontoSUCCESS.Thatis,aMAPcanfailbutitdoesnotsucceed.

webMethods Developer Users Guide Version 7.1.1

177

7 Inserting Flow Steps

The LOOP Step

TheLOOPsteprepeatsasequenceofchildstepsonceforeachelementinanarraythat youspecify.Forexample,ifyourpipelinecontainsanarrayofpurchaseorderlineitems, youcoulduseaLOOPsteptoprocesseachlineiteminthearray. Tospecifythesequenceofstepsthatmakeupthebodyoftheloop(thatis,thesetofsteps youwanttheLOOPtorepeat),youindentthosestepsbeneaththeLOOPasshowninthe followingexample. Simple LOOP step

The body of the loop must be indented beneath the LOOP step.

YoumayincludeanyvalidflowstepwithinthebodyofaLOOP,includingadditional LOOPsteps.ThefollowingexampleshowsapairofnestedLOOPs.Notehowthe indentationofthestepsdeterminestheLOOPtowhichtheybelong. Nested LOOP steps

The entire LOOP step is a child of the outer LOOP.

178

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

Specifying the Input Array

TheLOOPsteprequiresyoutospecifyaninputarraythatcontainstheindividual elementsthatwillbeusedasinputtooneormorestepsintheLOOP.Atruntime,the LOOPstepexecutesonepassoftheloopforeachmemberinthespecifiedarray.For example,ifyouwanttoexecuteaLOOPforeachlineitemstoredinapurchaseorder,you wouldusethedocumentlistinwhichtheorderslineitemsarestoredastheLOOPs inputarray. YouspecifythenameoftheinputarrayontheLOOPstepsPropertiespanel.Thearray youspecifycanbeanyofthefollowingdatatypes: Stringlist Stringtable Documentlist Objectlist LOOP properties

The LOOP step executes once for each member of the array specified in Input array.

Whenyoudesignyourflow,rememberthatbecausetheserviceswithintheloopoperate againstindividualelementsinthespecifiedinputarray,theymustbedesignedtotake elementsofthearrayasinput,nottheentirearray. Forexample,ifyourLOOPexecutesagainstadocumentlistcalledLineItemsthatcontains childrencalledItem,Qty,andUnitPrice,youwouldspecifyLineItemsastheInput arrayfor theLOOPstep,butserviceswithintheloopwouldtaketheindividualelementsof LineItems(forexample,Item,Qty,UnitPrice,andsoforth)asinput.

Collecting Output from a LOOP Step

IfyourLOOPstepproducesanoutputvariable,theservercancollectthatoutputintoan arrayinthepipeline. Todothis,youusetheOutput arrayparametertospecifythenameofthearrayvariable intowhichyouwanttheservertocollectoutputforeachiterationoftheloop.For example,ifyourloopchecksinventorystatusofeachlineiteminapurchaseorderand producesaStringcalledInventoryStatuseachtimeitexecutes,youwouldspecify InventoryStatusasthevalueofOutput array.Atruntime,theserverwillautomatically

webMethods Developer Users Guide Version 7.1.1

179

7 Inserting Flow Steps

transformInventoryStatustoanarrayvariablethatcontainstheoutputfromeachiteration oftheloop. Tocollectoutputfromeachpassoftheloop,specifythenameoftheoutputvariablethat youwanttheservertocollectforeachiteration.

Building a LOOP Step

UsethefollowingproceduretobuildaLOOPstepinaflowservice. To build a LOOP step 1 IfyouareinsertingaLOOPstepintoanexistingflowservice,displaythatservicein theeditorandselectthestepimmediatelyabovewhereyouwanttheLOOPstep inserted. Click ontheeditortoolbar.

2 3

CompletethefollowingfieldsonthePropertiespanel: For this property Comments Scope Specify Anoptionaldescriptivecommentforthisstep. Thenameofadocument(IDataobject)inthepipelineto whichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Themaximumnumberofsecondsthatthisstepshouldrun.If thistimeelapsesbeforethestepcompletes,theserverwaitsfor thesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example, %expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank. Label AnoptionalnameforthisspecificLOOPstep,oranull, unmatched,oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHor EXITstep,youmustspecifyavalueintheLabelproperty.For moreinformationabouttheBRANCHandEXITsteps,see TheBRANCHSteponpage 160orTheEXITStepon page 181. Input array ThenameofthearrayvariableonwhichtheLOOPwill operate.Thisvariablemustbeoneofthefollowingtypes: Stringlist,Stringtable,Documentlist,Objectlist.

Timeout

180

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

For this property Output array

Specify Thenameoftheelementthatyouwanttheservertocollect eachtimetheLOOPexecutes.Youdonotneedtospecifythis propertyiftheloopdoesnotproduceoutputvaluesorifyou arecollectingtheelementsofInput array.

Buildthebodyoftheloopusingthefollowingsteps: a b c Insertaflowstepusingthebuttonsontheeditortoolbar. Indenttheflowstepusing step. ontheeditortoolbartomakeitachildoftheLOOP

Setthepropertiesforthechildstepasneeded.

UsethePipelinetabtolinktheelementsoftheinputarraytotheinputvariables requiredbyeachchildoftheLOOPstep.Formoreinformationaboutusingthe Pipelinetab,seeChapter 8,MappingDatainaFlowService. Important! WhenyoubuildaLOOPstep,makesurethatyouspecifytheoutputarray variableintheLOOPOutput arraypropertybeforecreatingalinktotheoutputarray variablewithinaMAPorINVOKEstepinthebodyoftheLOOP.Ifyouspecifythe outputarrayvariableaftercreatingalinktoit,thelinkwillfailatruntime.Youcan testthestepinDevelopertoseeifthelinksucceeds.Ifthelinkfails,deletethelinkto theoutputarrayvariableandthenrecreateit.

The EXIT Step

TheEXITflowstepallowsyoutoexittheentireflowserviceorasingleflowstep.You specifywhetheryouwanttoexitfrom: Thenearestancestor(parent)LOOPorREPEATflowsteptotheEXITflowstep. TheparentflowstepoftheEXITflowstep. AspecifiedancestorflowsteptotheEXITflowstep. Theentireflowservice. WhenyouusetheEXITstep,youindicatewhetherexitingshouldreturnasuccessful conditionorafailurecondition.Iftheexitisconsideredafailure,anexceptionisthrown. Youcanspecifythetextoftheerrormessagethatisdisplayedbytypingitdirectlyorby assigningittoavariableinthepipeline.

webMethods Developer Users Guide Version 7.1.1

181

7 Inserting Flow Steps

ExamplesofwhentousetheEXITstepincludeto: Exitanentireflowservicefromwithinaseriesofdeeplynestedsteps. Throwanexceptionwhenyouexitafloworaflowstepwithouthavingtowritea JavaservicetocallService.throwError(). ExitaLOOPorREPEATflowstepwithoutthrowinganexception. ThefollowingflowservicecontainstwoEXITstepsthat,ifexecuted,willexitthenearest ancestorLOOPstep.IfthevalueofCreditCardTypeisnulloranemptystring,the matchingEXITstepexecutesandexitstheLOOPoverthe/PurchaseOrdersListstep. Use the EXIT step to exit the nearest ancestor LOOP step

This LOOP exits when....

...CreditCardType is null... ...or empty.

To build an EXIT step 1 IfyouareinsertinganEXITstepintoanexistingflowservice,displaythatservicein theeditorandselectthestepimmediatelyabovewhereyouwanttheEXITstep inserted. Click ontheeditortoolbar.

2 3

CompletethefollowingfieldsonthePropertiespanel: For this property Comments Label Specify Anoptionaldescriptivecommentforthisstep. Anoptionalnameforthisspecificstep,oranull,unmatched, oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHstep, youmustspecifyavalueintheLabelproperty.Formore informationabouttheBRANCHstep,seeTheBRANCH Steponpage 160.

182

webMethods Developer Users Guide Version 7.1.1

7 Inserting Flow Steps

For this property Exit from

Specify Theflowstepfromwhichyouwanttoexit.Specifyoneofthe following: Specify $loop $parent $flow Label To exit from the... NearestancestorLOOPorREPEATflowstep. Parentflowstep,regardlessofthetypeofstep. Entireflow. Nearestancestorflowstepthathasalabelthat matchesthisvalue. Note: Ifthelabelyouspecifydoesnotmatchthe labelofanancestorflowstep,theflowwillexit withanexception.

Signal

Whethertheexitistobeconsideredasuccessorafailure. Specifyoneofthefollowing: Specify SUCCES S FAILURE To Exittheflowserviceorflowstepwithasuccess condition. Exittheflowserviceorflowstepwithafailure condition.Anexceptionisthrownaftertheexit. YouspecifytheerrormessagewiththeFailure messageproperty.

Failure message

Thetextoftheexceptionmessageyouwanttodisplay.Ifyou wanttousethevalueofapipelinevariableforthisproperty, typethevariablenamebetween%symbols(forexample, %mymessage%). ThispropertyisnotusedwhenSignalissettoSUCCESS.

The MAP Step

TheMAPstepletsyouadjustthecontentsofthepipelineatanypointinaflowservice. WhenyoubuildaMAPstep,youcan: Preparethepipelineforusebyasubsequentstepintheflowservicebylinking, adding,anddroppingvariablesinthepipeline. Cleanupthepipelineafteraprecedingstepbyremovingfieldsthatthestepadded butarenotneededbysubsequentsteps. Movevariablesorassignvaluestovariablesinthepipeline.

webMethods Developer Users Guide Version 7.1.1

183

7 Inserting Flow Steps

Initializetheinputvaluesforaflowservice. Invokeseveralservices(transformers)inasinglestep. Mapdocumentsformoneformattoanother.Forexample,youcanmapadocument inanXMLformattoanebXMLformatoraproprietaryformat. Tip! TheMAPstepisespeciallyusefulforhardcodinganinitialsetofinputvaluesin aflowservice.Touseitinthisway,inserttheMAPstepatthebeginningofyourflow, andthenusetheSet Valuemodifiertoassignvaluestotheappropriatevariablesin Pipeline Out. FormoreinformationabouttheMAPstep,seeChapter 8,MappingDatainaFlow Service.

184

webMethods Developer Users Guide Version 7.1.1

Mapping Data in a Flow Service

186 186 191 212

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

webMethods Developer Users Guide Version 7.1.1

185

8 Mapping Data in a Flow Service

What Is Data Mapping?

Datamappingistheprocessofperformingtransformationstoresolvedatarepresentation differencesbetweenservicesordocumentformats.Bymapping,youcanaccomplishthe followingtypesofdatatransformations: Name transformationswheredifferentvariablenamesrepresentthesamedataitem.For example,oneserviceordocumentformatmightuseTelephoneasthenameofthe variablefortelephonenumberinformationandanothermightusePhoneNumber. Whenyouperformnametransformations,thevalueandpositionofavariableinthe document(IDataobject)structureremainthesame,butthenameofthevariable changes. Structural transformationswheredifferentdatastructuresrepresentadataitem.For example,oneserviceordocumentformatmightputthetelephonenumberinastring calledTelephone,andthenextmayexpecttofinditinanelementofadocument(IData object)arraycalledCustInfo.Whenyouperformstructuraltransformations,thevalue ofthevariableremainsthesame,butthedatatypeorpositionofthevariableinthe document(IDataobject)structurechanges. Value transformationswheredifferentformatsrepresentthesamevalue.Thisoccurs commonlywithdateandtimevariables,where,forinstance,onevariablemightuse 01/01/99andanotherJanuary1,1999.Inothercases,yourservicesordocument formatsmightusedifferentnotationsforstandardcodesorvalues,differentcurrency units,oradifferentsystemofweightsandmeasures(metricinsteadoftheU.S. CustomaryorBritishImperialsystems).Whenyouperformvaluetransformations, thenameandpositionofthevariableremainthesame,butthedatacontainedinthe variablechanges.(Forexample,youcanchangetheformatofadate,concatenatetwo strings,oraddthevaluesoftwovariablestogether.) Whenyoubuildflowservicesorconvertbetweendocumentformats,youmayneedto performone,two,oralloftheabovetypesofdatatransformation.ThewebMethodsflow languageprovidestwowaysforyoutoaccomplishdatatransformationsbetween servicesanddocumentformats:youcanmapvariablestoeachother(createlinks)oryou caninserttransformers. webMethodsDeveloperprovidesagraphicalenvironmentinwhichyoucanperform datamappingbetweenvariablesandformats,whichisthePipelinetab.

What Does the Pipeline Tab Contain?

ThePipelinetaboffersagraphicalrepresentationofallofyourdatathroughwhichyou canmapdataandinspectthecontentsofthepipeline.Youusethetoolsonthistabto routevariables(data)betweenservicesorbetweendocumentformats. ThePipelinetabdisplaysintheeditorforinvokedservices(INVOKEsteps)orMAPsteps inaflowservice.ThecontentsofthistabforINVOKEstepsareslightlydifferentthanfor MAPsteps.

186

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Pipeline Tab for an INVOKE Step

ForanINVOKEstep,thePipelinetabdepictstwostagesofthepipelinewithrespecttothe selectedserviceintheeditor. Pipeline tab for an INVOKE step (service)
The Pipeline tab depicts the services input and output with respect to the expected pipeline.

This stage...
1

Represents... Theexpectedstateofthepipelinejustbeforetheselectedservice executes. Pipeline Indepictsthesetofvariablesthatareexpectedtobeinthe pipelinebeforetheserviceexecutes(basedonthedeclaredinput andoutputparametersoftheprecedingservices). Service Indepictsthesetofvariablestheselectedserviceexpectsas input(asdefinedbyitsinputparameters). OnthePipelinetab,youcaninsertpipelinemodifiersatthisstage toadjustthecontentsofthepipelinetosuittherequirementsofthe service.Forexample,youcanlinkvariables,assignvaluesto variables,dropvariablesfromthepipeline,oraddvariablestothe pipeline.Modificationsthatyouspecifyduringthisstageare performedimmediatelybeforetheserviceexecutesatruntime.

webMethods Developer Users Guide Version 7.1.1

187

8 Mapping Data in a Flow Service

This stage...
2

Represents... Theexpectedstateofthepipelinejustaftertheserviceexecutes. Service Outdepictsthesetofvariablesthattheselectedservice producesasoutput(asdefinedbyitsoutputparameters). Pipeline Outdepictsthesetofvariablesthatareexpectedtobeinthe pipelineaftertheserviceexecutes.Itrepresentsthesetofvariables thatwillbeavailabletothenextserviceintheflow.Iftheselected service(INVOKEstep)isthelaststepintheflowservice,Pipeline Out displaystheoutputvariablesfortheflowservice(asdeclaredonthe Input/Outputtab). OnthePipelinetab,youcaninsertpipelinemodifiersatthisstage toadjustthecontentsofthepipeline.Forexample,youcanlink variables,assignvaluestovariables,dropvariablesfromthe pipeline,oraddvariablestothepipeline.Modificationsthatyou specifyduringthisstageareperformedimmediatelyafterthe serviceexecutesatruntime.

Note: Developerdisplayssmallsymbolsnexttoavariableicontoindicatevalidation constraints.Developeruses toindicateanoptionalvariable.Developerusesthe symboltodenoteavariablewithacontentconstraint.Forinformationaboutapplying constraintstovariables,seeApplyingConstraintstoVariablesonpage 255.

188

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Pipeline Tab for a MAP Step

ForaMAPstep,thePipelinetabdisplaysasinglestageofthepipeline.ThePipelinetab containstwosetsofvariables:Pipeline InandPipeline Out.Betweenthesesetsofvariables, thePipelinetabcontainsacolumnnamedTransformers. Pipeline tab for a MAP step

ThePipeline IncolumnrepresentsinputtotheMAPstep.Itcontainsthenamesofallof thevariablesinthepipelineatthispointintheflow. TheTransformers columndisplaysanyservicesinsertedintheMAPsteptocomplete valuetransformations.FormoreinformationaboutinvokingservicesinaMAPstep, seeInsertingaTransformerintoaMAPSteponpage 214. ThePipeline Out columnrepresentstheoutputoftheMAPstep.Itcontainsthenames ofvariablesthatwillbeavailableinthepipelinewhentheMAPstepcompletes. WhenyoufirstinsertaMAPstepintoyourflow,Pipeline InandPipeline Outareidentical. However,iftheMAPstepistheonlystepintheflowserviceoristhelaststepintheflow service,Pipeline Outalsodisplaysthevariablesdeclaredasoutputintheflowservice. OnthePipelinetab,youcaninsertpipelinemodifierstoadjustthecontentsofthe pipeline.Forexample,youcanlinkvariablesfromPipeline IntoservicesinTransformers. Youcanalsousepipelinemodifierstoassignvaluestopipelinevariables,dropvariables fromthepipeline,oraddvariablestothepipeline.

webMethods Developer Users Guide Version 7.1.1

189

8 Mapping Data in a Flow Service

Pipeline Modifiers
Pipelinemodifiersarespecialcommandsthatyouapplytoadjustthepipelineatrun time.Theyexecuteimmediatelybeforeoraftertheselectedserviceortransformer, dependingonwhereyouaddthemonthePipelinetab.Usethefollowingbuttonstoadd pipelinemodifierstothepipeline: Use this modifier...
Link

To... Link a pipeline variable to a service variable.TheLinkmodifierletsyou resolvevariablenameanddatastructuredifferencesbylinking (copying)thevalueofonevariabletoanotheratruntime.For informationaboutusingthispipelinemodifier,seeLinking Variablesonpage 192. Drop a variable from the pipeline.TheDropmodifierremoves extraneousvariablesfromthepipeline.Forinformationabout usingthispipelinemodifier,seeDroppingVariablesfromthe Pipelineonpage 210. Assign a value to a variable.TheSet Valuemodifierhardcodesa valueforavariable.Forinformationaboutthispipelinemodifier, seeAssigningValuestoPipelineVariablesonpage 206.

Drop

Set Value

Printing the Pipeline Tab

ThefollowingproceduredescribeshowtousetheView as HTMLcommandtoproducea printableversionofthePipelinetab. Note: WhenyouviewthePipelinetabasHTML,theresultingHTMLpagedisplays onlytheportionofthepipelinethatisvisiblewithinthetab.BeforeyouselecttheView as HTMLcommand,makesurethePipelinetabdisplaysthepartofthepipelinethatyou wanttoviewasHTML. To print the Pipeline tab 1 2 3 4 OpentheflowserviceforwhichyouwanttoprintthePipelinetab. Intheeditor,selecttheINVOKEorMAPstepforwhichyouwanttoprintthePipeline tab. ClickanywhereonthePipelinetab. ScrollorresizethePipelinetabtodisplaytheportionofthepipelineyouwanttoview asHTML.

190

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

5 6

OntheFilemenu,clickView as HTML. DevelopercreatesanHTMLpageanddisplaysitinyourdefaultbrowser. Ifyouwanttoprintthepipeline,useyourbrowsersprintcommand.

Basic Mapping Tasks

Basicmappingtasksarethetasksyouperformtomanagethepipelinecontentsandthe valuesofvariablesinthepipeline.OnthePipelinetab,youcanperformthefollowing basicmappingtasks: Link variables to each other.Youcancopythevalueofavariableinoneserviceor documentformattoavariableinanotherserviceordocumentformat. Assign values to variables.Youcanhardcodevariablevaluesorassignadefaultvalueto variables. Drop variables from the pipeline.Youcanremovepipelinevariablesthatarenotusedby subsequentservicesinaflow. Add variables to the pipeline.Youcanaddvariablesthatwerenotdeclaredasinputor outputparametersoftheflowservice.Youcanalsoaddinputandoutputvariables forservicesthattheflowserviceinvokes(internallyinvokedservices). Thefollowingtableidentifiesthesectionsthatdescribethebasicmappingtasks. For more information about... Linkingvariables Linkingvariablesofdifferentdatatypes Linkingtoandfromarrayvariables Deletinglinksbetweenvariables Applyingconditionstolinksbetweenvariables Assigningvaluestopipelinevariables Droppingvariablesfromthepipeline Addingvariablestothepipeline Searchingforvariablesinaneditortree See page... 192 199 201 204 204 206 210 211 58

webMethods Developer Users Guide Version 7.1.1

191

8 Mapping Data in a Flow Service

Linking Variables
Whenyouwanttocopythevalueofavariableinaserviceordocumentformattoanother variable,youlinkthevariables.Developerconnectsserviceandpipelinevariablesonthe Pipelinetabwithalinecalledalink.Creatingalinkbetweenvariablescopiesthevalue fromonevariabletoanotheratruntime. Withinaflow,Developerimplicitlylinksvariableswhosenamesarethesameandwhose datatypesarecompatible.Forexample,theserviceinthefollowingflowtakesavariable calledAcctNumber.BecauseavariablebythisnamealreadyexistsinPipeline In,itis automaticallylinkedtotheAcctNumbervariableinService In.Developerconnects implicitlylinkedvariableswithagraylink. Implicit links between pipeline and service variables

Pipeline variables are automatically linked to service variables of the same name.

Important! ThePipelinetabdoesnotdisplayimplicitlinksforaMAPstep. Incaseswheretheservicesinaflowdonotusethesamenamesforapieceof information,usethePipelinetabtoexplicitlylinkthevariablestoeachother.Explicit linkingishowyouaccomplishnameandstructuretransformationsrequiredinaflow. Developerconnectsexplicitlylinkedvariableswithasolidblackline. OntheinputsideofthePipelinetab,usetheLink modifiertolinkavariablefromthe pipelinetotheservice.Inthefollowingexample,theserviceexpectsavaluecalled OrderTotal,whichisequivalenttothepipelinevariableBuyersTotal(thatis,theyare simplydifferentnamesforthesamedata).TousethevalueofBuyersTotalasthevaluefor OrderTotal,youlinkthepipelinevariabletotheserviceusingtheLinkmodifier. Atruntime,theserverwillcopythevaluefromthesourcevariable(BuyersTotal)tothe targetvariable(OrderTotal)beforeexecutingtheservice.

192

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Linking the pipeline to service input

When a pipeline variable name is different from the one used by the service, use the Link modifier to connect them.

Important! DonotlinkvariableswithdifferentObjectconstraints.Ifyoulinkvariables withdifferentobjectconstraintsandinput/outputvalidationisselected,theruntime resultisundefined. Alltheoutputvariablesthataserviceproducesareautomaticallyplacedinthepipeline. JustasyoucanlinkvariablesfromthePipeline Instagetoaservicesinputvariables,you canlinktheoutputfromaservicetoadifferentvariableinPipeline Out. Inthefollowingexample,avariablecalledTransNumberislinkedtothefieldNumina documentcalledTransactionRecord.Atruntime,theserverwillcopythevalueof TransNumbertoNum,andbothTransNumberandNumwillbeavailabletosubsequent servicesintheflow.

webMethods Developer Users Guide Version 7.1.1

193

8 Mapping Data in a Flow Service

Linking service output to the pipeline

When an output variable name is different from the name in the pipeline, use the Link modifier to connect them.

Developer automatically adds a services output variables to the pipeline and implicitly links them.

Whenyoulinkvariablesinthepipeline,keepthefollowingpointsinmind: Thevariablethatyouarelinkingfromisthesource.Forexample,whenyoulinka variableinPipeline IntooneinService In,thePipeline Invariableisthesource.When youlinkavariableinService OuttooneinPipeline Out,theService Outvariableisthe source. Thevariableyouarelinkingtoisthetarget.Forexample,whenyoulinkavariablein Pipeline IntooneinService In,theService Invariableisthetarget.Whenyoulinka variableinService OuttooneinPipeline Out,thePipeline Outvariableisthetarget. AService InvariablecanbethetargetofmorethanoneLinkmodifieronlyifyouuse arrayindexingorifyouplaceconditionsonthelinkstothevariable. Bylinkingvariablestoeachother,youarecopyingdatafromthesourcevariabletothe targetvariable.(Documents,however,arecopiedbyreference.Formoreinformation, seeWhatHappensWhenIntegrationServerExecutesaLinkBetweenVariables?on page 196.) Targetvariablescanbeconnectedtoonlyonesourcevariable.Afteryoudrawalink toatargetvariable,youcannotdrawanotherlinktothetargetvariable.(Two exceptionstothisruleinvolvearrayvariablesandconditionallinks.Formore informationaboutlinkingarrayvariables,seeLinkingtoandfromArrayVariables onpage 201.Formoreinformationaboutplacingconditionsonlinksbetween variables,seeApplyingConditionstoLinksBetweenVariablesonpage 204.

194

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

YoucannotcreatealinktoavariableifyoualreadyusedtheSet Valuemodifierto assignavaluetoavariable. AfteraLinkmodifierisexecuted,boththesourceandtargetvariablesexistinthe pipeline.Thetargetvariabledoesnotreplacethesourcevariable. To create a link between variables 1 2 3 Intheeditor,selecttheINVOKEorMAPstepcontainingthevariablesyouwantto link. ClickthePipelinetab. IfyouwanttocreatealinkbetweenavariableinPipeline InandoneinService In,dothe following: a b c 4 InPipeline In,clickthepipelinevariableyouwanttouseasthesourcevariable. InService In,clicktheinputvariableyouwanttouseasthetargetvariable. Click onthetoolbar.

IfyouwanttocreatealinkbetweenavariableinService OutandoneinPipeline Out,do thefollowing: a b c InService Out,clicktheoutputvariableyouwanttouseasthesourcevariable. InPipeline Out,clickthepipelinevariableyouwanttouseasthetargetvariable. Click onthetoolbar.

Notes:

Ifthevariabletypesareincompatibleandcannotbelinkedtooneanother, Developerdisplaysamessagestatingthattheoperationisnotallowed. Ifyoucreatedalinktoorfromanarrayvariable,youmustspecifywhichelement inthearrayyouarelinkingtoorfrom.Formoreinformationaboutarraylinking, seeLinkingtoandfromArrayVariablesonpage 201. Ifyouwanttoplaceaconditionontheexecutionofthelink,seeApplying ConditionstoLinksBetweenVariablesonpage 204. DonotlinkvariableswithdifferentObjectconstraints.Ifyoulinkvariableswith differentobjectconstraintsandinput/outputvalidationisselected,theruntime resultisundefined.

Tip! Youcanalsouseyourmousetolinkvariablestooneanother.Todothis,selectthe sourcevariableanddragyourmousetotheappropriatetargetvariable.

webMethods Developer Users Guide Version 7.1.1

195

8 Mapping Data in a Flow Service

Tip! ToscrollthroughthePipeline InandPipeline Outtreesindependently,displaythe lefthandscrollbar.Click todisplaythelefthandscrollbar.Click tohidethe lefthandscrollbar.ThelefthandscrollbarisonlyavailableonthePipelinetabfora MAPstep.Whenyouexpandatransformer,Developerhidesthelefthandscrollbar automatically.

What Happens When Integration Server Executes a Link Between Variables?

Whenexecutingalinkbetweenvariablesatruntime,IntegrationServerdoesoneofthe following: Copiesthevaluefromthesourcevariabletothetargetvariable.Forexample,when youlinkasourceStringvariabletoatargetStringvariable,IntegrationServercopies thevalueofthesourceStringtothetargetString.Thisiscalledcopyingbyvalue. Createsareferencetothesourcevariableandusesthereferenceasthevalueofthe targetvariable.Forexample,whenexecutingalinkbetweenasourcedocumentanda targetdocument,IntegrationServercreatesareferencetothesourcedocumentvalue andusesthereferenceasthevalueofthetargetdocument.Thisiscalledcopyingby reference. IntegrationServercopiesbyvaluewhenthesourceortargetvariableisaString.(An exceptiontothisbehavioristhatwhenexecutingalinkfromaStringtoanObject,the IntegrationServercopiesbyreference.) Whenexecutinglinksbetweenallothertypesofvariables,theIntegrationServercopies byreference.Copyingbyreferencesignificantlyreducesthememoryandtimerequired forexecutingalinkatruntime. Whenavalueiscopiedbyreference,anychangesyoumaketothevalueofthesource variableinsubsequentflowstepsaffectthetargetvariable.Thisisbecausethevalueof thesourcevariableisthevalueofthetargetvariable.Thetargetvariabledoesnotcontain acopyofthesourcevariablevalue.If,inalaterflowstep,youusedtheSet Valuemodifier toassignavaluetothesourcevariable,youwouldbechangingthevalueofthetarget variableaswell.(Thetargetvariablereferencesthevalueofthesourcevariable.) ThefollowingimagesshowaseriesofMAPstepsinaflowservice.Inthisexample,the valueofthesourcevariableischangedafterthelinktothetargetvariableexecutes.This actionchangesthevalueofthetargetvariableaswell.

196

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

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.

webMethods Developer Users Guide Version 7.1.1

197

8 Mapping Data in a Flow Service

Whenthisflowserviceexecutes,itreturnsthefollowingresults. 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.

InStep3,thevalueoftheString1inDocument1wassettomodified.However,the valueofString1inDocument2changedalso.ThisisbecauseinStep2oftheflowservice, thevalueofDocument1wascopiedtoDocument2byreference.Changestothevalueof Document1inlaterflowstepsalsochangethevalueofDocument2. Topreventthevalueofthetargetvariablefrombeingoverwrittenbychangestothevalue ofthesourcevalueinsubsequentstepsintheflowservice,youcandooneofthe following: Whenworkingwithdocumentvariables,linkeachchildofthedocumentvariable individually.Thismethodcanbetimeconsumingandmightsignificantlyincreasethe memoryandtimerequiredtoruntheservice.However,thismightbethebest approachifthetargetdocumentvariableneedsonlyafewvaluesfromthesource documentvariable. Afteryoulinkthesourcevariabletoatargetvariable,usetheDropmodifiertodrop thesourcevariable.Onlythetargetvariablewillhavethereferencetothedata.This methodensuresthatthevalueofthetargetvariablewillnotbeoverwrittenina subsequentstep,butdoesnotincreasethememoryandtimerequiredtoexecutethe service. Createaservicethatperformsacopybyvalue.Insertthisservice(asanINVOKEstep orasatransformer)andlinkthevariablestotheserviceinsteadoflinkingthemto eachother.(Inthecaseofdocumentvariables,youcouldcreateaJavaservicethat clonestheIDataobjectunderlyingthedocument.)Insituationswhereyoulinkone documentvariabletoanother,usingacloningservicewouldrequirelesstimethan linkingthecontentsofadocumentvariablefieldbyfield.

Linking to Document and Document List Variables

Whenworkingwithdocumentvariablesinthepipeline,youcanlinkasourcevariableto thedocumentvariableortothechildrenofthedocumentvariable.Keepthefollowing pointsinmindwhenlinkingtodocumentordocumentlistvariables: Adocument(oradocumentlist)anditschildrencannotbothbetargets.Aftera documentordocumentlististhetargetofaLinkmodifier,itschildrencannotbethe targetsofLinkmodifiers. AfterthechildvariableofadocumentordocumentlististhetargetofaLinkmodifier, theparentdocumentordocumentlistcannotbeatargetofaLinkmodifier.

198

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Ifyoulinkfromadocumentvariabletoanotherdocumentvariable,thestructureof thesourcedocumentvariableoverwritesthestructureofthetargetdocument variable.

Linking Variables of Different Data Types

OnthePipelinetab,youcanlinkdifferent,butcompatible,datatypestooneanother.For example,youcouldlinkaStringvaluecalledAccountNumbertoaStringlistcalled Accounts.Atruntime,theserverautomaticallyperformsthestructuraltransformation necessarytolinkthedatainAccountNumbertoAccounts.(Inthiscase,thetransformation willresultinasingleelementStringlist.)Bylinkingdifferentdatatypestooneanother, youcanperformstructuraltransformations. Ifyoulinkvariablesofdifferentdatatypes,keepthefollowingpointsinmind: Notalldatatypescanbelinkedtooneanother.Youcannotlinkadocument(IData object)toaString,forinstance.Iftwodatatypesareincompatible,Developerwillnot allowyoutoconnectthemwiththeLinkmodifier. Youcanonlylinkavariabletoanothervariableofthesameprimitivetype.The primitivetypereferstothedatatypeofthevariablewhenalldimensionalityis removed.Forexample,theprimitivetypeforaStringlistoraStringtablewouldbe String.Twoexceptionstothisruleare:anyvariablecanbelinkedtoanObjectoran Objectlistvariable,andanObjectcanbelinkedtoanydatatype.(Ifthereisatype mismatchbetweentheObjectorObjectlistandtheothervariableatruntime,the IntegrationServerdoesnotexecutethelink.) ObjectandObjectlistvariablesconstrainedwithanassignedJavaclassshouldbe linkedonlytootherObjectandObjectlistvariablesofthesameJavaclassortoObject andObjectlistvariablesofunknowntype.AlthoughDeveloperpermitsalink betweenconstrainedObjectswithdifferentJavaclasses,theruntimeresultis undefined.FormoreinformationaboutspecifyingJavaclassesforObjects,seeJava ClassesforObjectsonpage 407. Whenyoulinkbetweenscalarandarrayvariables,youcanspecifywhichelementof thearrayvariableyouwanttolinktoorfrom.Scalarvariablesarethosethatholda singlevalue,suchasString,document,andObject.Arrayvariablesarethosethathold multiplevalues,suchasStringlist,Stringtable,documentlist,andObjectlist.For example,youcanlinkaStringtothesecondelementofaStringlist.Alternatively,you canlinkthesecondelementinaStringlisttoaString. Whenyoulinkbetweenscalarandarrayvariablesandyoudonotspecifywhich elementinthearrayvariablethatyouwanttolinktoorfrom,Developerusesthe defaultbehaviortodeterminethevalueofthetargetvariable. Formoreinformationaboutthedefaultbehaviorforlinkingarrayvariables,seeDefault PipelineRulesforLinkingtoandfromArrayVariablesonpage 409.

webMethods Developer Users Guide Version 7.1.1

199

8 Mapping Data in a Flow Service

Examples of Structural Transformations on the Pipeline Tab ThestructuraltransformationsyoucanperformbylinkingvariablesonthePipelinetab canbemorecomplexthantransformingaStringtoaStringlist.Forexample,youcan combinetwoStringlistsintoonedocumentlistthroughlinking.Thefollowingsection explainsacommonstructuraltransformationthatyoucancompletevialinkinginthe pipeline. Converting a String List to a Document List YoucanconvertaStringlisttoadocumentlistusingthePipelinetab.Inthefollowing diagram,aLististheStringlistyouwanttoconverttoadocumentlist.Thevariable documentLististhedocumentlisttowhichyouwanttocopythevaluescontainedinthe Stringlist.documentListhasaStringchildaString.ToconverttheStringlisttoadocument list,linkaListtoaString. Converting a String list to a document list

TwoStringlistscanbecombinedintoonedocumentlistthroughdatamappinginthe pipeline.Forexample,ifintheabovescenarioyoualsohadaStringlistvariablenamed bList,anddocumentListhadtwoStringchildrennamedaStringandbString,youcould combinethetwoStringlistsbylinkingaListtoaStringandbListtobString. Converting two String lists to a document list

200

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Tip! YoucanalsoconvertaStringlisttoadocumentlist(IData[]object)byinvoking thebuiltinservicepub.list:stringListToDocumentList.Youcaninserttheserviceasan INVOKEsteporasatransformer.Formoreinformationabouttransformers,see WhatAreTransformers?onpage 212.Formoreinformationaboutbuiltinservices, seethewebMethodsIntegrationServerBuiltInServicesReference.

Linking to and from Array Variables

Whenyoulinktoorfromanarrayvariable(Stringlist,Stringtable,documentlist,or Objectlist),youcanspecifywhichelementinthearrayyouwanttolinktoorfrom.After youlinkthevariables,youspecifytheindexthatrepresentsthepositionoftheelementin thearray. ForStringlistsandObjectlists,youcanspecifytheindexforthelistelementyouwant tolink.Forexample,youcanlinkthethirdelementinaStringlisttoaString. ForStringtables,youcanspecifytherowandcolumnindexesforthecellsyouwant tolink.Forexample,youcanlinkthevalueoftheelementinthethirdcolumnofthe secondrowofaStringtabletoaString. Fordocumentlists,youcanspecifytheindexforthedocumentthatyouwanttolink. Forexample,youcanlinktheseconddocumentinadocumentlisttoadocument variable. Foravariableinadocumentlist,youcanspecifytheindexofthedocumentthat containsthevaluethatyouwanttolinktoorfrom.Forexample,ifthedocumentlist POItemscontainstheStringItemNumber,youcanlinktheItemNumbervaluefromthe secondPOItemsdocumenttoaStringvariable. Forexample,supposethatabuyersaddressinformationisinitiallystoredinaStringlist. However,theinformationmightbeeasiertoworkwithifitwerestoredinadocument. TomaptheinformationintheStringlisttoadocument,createalinkbetweentheString listandeachfieldinthedocument.Then,specifyanindexvalueforeachlink.Inthe followingpipeline,theelementsinbuyerAddressStringlistaremappedtotheaddress document.

webMethods Developer Users Guide Version 7.1.1

201

8 Mapping Data in a Flow Service

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: DeveloperusesbluelinksonthePipelinetabtoindicatethatproperties (conditionsorindexvaluesforarrays)havebeenappliedtothelinkbetween variables. TospecifytheindexfortheelementinthebuyerAddressvariabletobecopiedtothe FirstNamefield,selectthelinkbetweenthevariables,clicktheIndicespropertysEdit buttoninthePropertiespaneltospecifytheindex. Ifthesourceortargetvariableisanarray,Developerdisplaysatextboxnexttothe variable(inthiscase,buyerAddress).Ifthesourceortargetvariableisnotanarray, DeveloperdisplaysthewordsFieldnotindexablenexttothevariablename(inthis case,FirstName).Forexample,ifyouwanttolinkthefirstelementofthebuyerAddress variabletotheFirstNamefieldinaddress,type0inthefieldnexttobuyerAddress.(Index numberinginarraysbeginsat0.) Link indices

Indicates the index of the element in the buyerAddress String list that you want to copy to the FirstName field. Indicates the target variable is not an array.

202

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Guidelines for Linking to and from Array Variables Whenyouarelinkingtoorfromanarrayvariable,keepthefollowingpointsinmind: Tolinktoorfromanelementinanarrayvariable,youneedtoknowtheindexforthe elementspositioninthearray.Arrayindexnumberingbeginsat0(thefirstelement inthearrayhasanindexof0,thesecondelementhasanindexof1,andsoon). Todynamicallyspecifytheindex,youcansettheindextothevalueofapipeline variable.ThevariableyouspecifymustbeaString.Touseapipelinevariable,specify thevariablenameenclosedinpercentsigns(%).Forexample,ifthepipelinecontains thevariableitemNumberthatwillcontaintheindexyouwanttouseatruntime, specify%itemNumber%fortheindex.Forthelinktoexecutesuccessfullyatruntime, thevalueofthevariablemustbeanonnegativeinteger. Ifyoulinktoanarrayvariableandspecifyanindexthatdoesnotexist,Developer increasesthelengthofthearraytoincludethespecifiedarrayindex.Forexample, supposethataStringlisthaslength3.YoucanlinktotheStringlistandspecifyan indexof4;thatis,youcanlinktothefifthpositionintheStringlist.Atruntime,the IntegrationServerincreasesthelengthoftheStringlistfrom3to5. EachelementinanarraycanbethesourceortargetofaLinkmodifier;thatis,each elementinthearraycanbethestartorendofalink.Forexample,ifasourceString listvariablecontainsthreeelements,youcanlinkeachofthethreeelementstoa targetvariable. Ifthesourceandtargetvariablesarearrays,youcanspecifyanindexforeach variable.Forexample,youcanlinkthethirdelementinasourceStringlisttothefifth elementintargetStringlist. Ifyoudonotspecifyanarrayindexforanelementwhenlinkingtoorfromarrays, thedefaultbehaviorofthePipelinetabwillbeused.Forinformationaboutthedefault behaviorofthePipelinetab,seeDefaultPipelineRulesforLinkingtoandfromArray Variablesonpage 409. IfyouarelinkingtoorfromaStringtable,youneedtospecifyanindexvalueforthe rowandcolumn. Whenyoulinkadocumentordocumentlistvariabletoanotherdocumentor documentlistvariable,thestructureofthesourcevariabledeterminesthestructureof thetargetvariable.Formoreinformation,seeLinkingtoDocumentandDocument ListVariablesonpage 198. Thefollowingprocedureexplainshowtolinktoorfromanarrayvariable.

webMethods Developer Users Guide Version 7.1.1

203

8 Mapping Data in a Flow Service

To create a link to or from an array variable 1 2 3 4 5 6 CreatealinkbetweenthevariablesusingtheproceduredescribedinTocreatealink betweenvariablesonpage 195. Clickthelinkthatconnectsthevariables. OnthePropertiespanel,clicktheIndicespropertysEditbutton.Developerdisplays theLinkIndicesdialogbox. Ifthesourcevariableisanarrayvariable,underSource, nexttothesourcevariable name,typetheindexthatcontainsthevalueyouwanttolink. Ifthetargetvariableisanarrayvariable,underDestination,nexttothedestination variablename,typetheindextowhichyouwanttolinkthesourcevalue. ClickOK. Note: Atruntime,thelink(copy)failsifthesourcearrayindexcontainsanullvalueor ifyouspecifyaninvalidsourceortargetindex(suchasaletterornonnumeric character).TheIntegrationServergeneratesjournallogmessages(atdebuglevel6or higher)whenlinkstoorfromarrayvariablesfail.

Deleting Links Between Variables

Usethefollowingproceduretodeletethelinkcreatedbetweenvariables.Whenyou deletethelink,thevariablesarenolongerlinked.Developeralsodeletesanyproperties youappliedtothelink. To delete a link between variables 1 2 OnthePipelinetab,selectthelinkthatyouwanttodelete. OntheEditmenu,clickDelete. Tip! Youcanalsodeletealinkbyselectingitandthenclicking toolbarorpressingtheDELETEkey. onthePipelinetab

Applying Conditions to Links Between Variables

Youcanplaceconditionsonthelinksyoudrawbetweenvariables.Atruntime, webMethodsIntegrationServerevaluatestheconditionandexecutesthelink(copiesthe value)onlyiftheconditionevaluatestotrue. Aconditionconsistsofoneormoreexpressionsthatyouwriteusingthesyntaxthat Developerprovides.Anexpressioncancheckfortheexistenceofavariableinthe pipeline,checkforthevalueofavariable,orcompareavariabletoanothervariable.For example,inthefollowingservice,youmightwanttolinktheBuyersTotalvariablein Pipeline IntotheOrderTotalvariableinService InonlyiftheBuyersTotalhasavaluethatis

204

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

notnull.AfteryouconnectthetwovariableswiththeLinkmodifier,youwouldeditthe propertiesandaddtheconditionthatneedstobetrue. A blue link indicates that a condition is applied to the link connecting the variables

Use the Properties panel to view or create a condition for the link.

DeveloperusesabluelinkonthePipelinetabtoindicatethatproperties(thatis, conditionsorindexvaluesforarrays)havebeenappliedtoalinkbetweenvariables. Note: Youcannotaddconditionstothelinksbetweenimplicitlylinkedvariables. Linking Multiple Source Variables to a Target Variable Byapplyingconditionstothelinksbetweenvariables,youcanlinkmorethanonesource variabletothesametargetvariable.Whenyoudrawmorethanonelinktothesame targetvariable,atmost,onlyoneoftheconditionsyouapplytothelinkscanbetrueat runtime.Theconditionsmustbemutuallyexclusive. Atruntime,webMethodsIntegrationServerexecutesallconditionallinkswhose conditionsevaluatetotrue.Ifmorethanoneconditionallinktothesametargetvariable evaluatestotrue,thevalueofthetargetvariablewillbetheresultofwhicheverlink executeslast.Becausetheorderinwhichlinksareexecutedatruntimeisnotguaranteed, thefinalvalueofthetargetvariablemayvary. Tip! Iftheconditionsforlinkstothesametargetvariablearenotmutuallyexclusive, considerusingaflowservicecontainingaBRANCHstepinstead.InBRANCHsteps, childstepsareevaluatedinatoptobottomsequence.webMethodsIntegrationServer executesthefirstchildstepthatevaluatestotrueandskipstheremainingchildsteps. FormoreinformationabouttheBRANCHstep,seeTheBRANCHStepon page 160.

webMethods Developer Users Guide Version 7.1.1

205

8 Mapping Data in a Flow Service

To apply a condition to the link between variables 1 2 3 4 CreatealinkbetweenthevariablesusingtheproceduredescribedinTocreatealink betweenvariablesonpage 195. Clickthelink(blackline)thatconnectsthevariables. OnthePropertiespanel,settheEvaluate copy conditionpropertytoTrue. IntheCopy conditionpropertytextbox,typetheconditionyouwanttoplaceonthe link. Forinformationaboutthesyntaxusedinconditions,seeAppendix D,Conditional Expressions. Important! Whendrawingmorethanonelinktothesametargetvariable,makesure thattheconditionsassignedtoeachlinkaremutuallyexclusive. Note: Youcantemporarilydisabletheconditionplacedonalink.Formore information,seeDisablingaConditionPlacedonaLinkBetweenVariableson page 294.

Assigning Values to Pipeline Variables

TheSet Value modifierallowsyoutoassignvaluestovariablesinService InorPipeline Out.Youuseittoexplicitlyhardcodeaspecificvalueinavariable.Youcanalsouseit toassignadefaultvaluetoavariable. ByattachingaSet Value modifiertoavariable,youinstructtheservertowritea specificvaluetothatvariableatruntime.Thisactionoccursjustbeforetheselected serviceisexecuted(ifyouattachthemodifiertoavariableinService In)orimmediately aftertheselectedserviceisexecuted(ifyouattachthemodifiertoavariableinPipeline Out).

206

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Hardcoding the value of a variable

You use the Set Value modifier to assign a value to a variable.

Toview(orchange)thevaluethatisassignedtotheSet Valuemodifier,doubleclickthe iconnexttothevariablesnametoopentheInputFordialogbox. Input For dialog box

Specify the value that you want the server to assign to this variable at run time.

Assigning a Default Value to a Variable

OnecommonuseoftheSet Valuemodifieristospecifyadefaultvalueforavariable(that is,avaluethatisonlyassignedifthevariableisnullatruntime).TousetheSet Value modifierinthisway,disabletheOverwrite pipeline valuecheckboxintheInputFordialog box.Thisinstructstheservertousethespecifiedvalueonlywhentheselectedvariableis null. Note: Ifavariabletowhichyouassignedadefaultvalueisimplicitlylinkedtoanother variableinthepipeline,DeveloperdisplaysagraylinkonthePipelinetabconnecting thevariablesbeneaththe icon.

Initializing Variables in a Flow Service

YoucanusetheSet ValuemodifierwiththeMAPsteptohardcodeaninitialsetofinput valuesinaflowservice.Touseitinthisway,inserttheMAPatthebeginningofyour flow,andthenusetheSet Valuemodifiertoassignvaluestotheappropriatevariablesin Pipeline Out.

webMethods Developer Users Guide Version 7.1.1

207

8 Mapping Data in a Flow Service

Referencing Other Variables

Inadditiontoassigningaliteralvaluetoavariable,theSet Valuemodifierletsyouassign thevalueofanotherStringvariabletoaStringvariable.(Youmightdothisifyouwanted toderivethedefaultvaluefromavariableinthepipelineatruntime,forexample.) TospecifyavariablenamewiththeSet Valuemodifier,enclosethenameofthatvariable between%symbolsandthenenablethePerform variable substitutionoption.Thisoption instructstheservertointerpretyourvalueasavariablereferenceratherthanaliteral value. Referencing variables
Enclose the variable name in % symbols...

...and the select the variable-substitution option.

YoucanalsoformatStringvaluesbyspecifyingoneormorepipelinevariablesin conjunctionwithaliteralvalue.Forexample,ifyouspecified(%areaCode%) %Phone%,the resultingstringwouldbeformattedtoincludetheparenthesesandspace.Ifyouspecified %firstName% %initial%. %lastName%,theperiodandspacingwouldbeincludedinthe value.

Setting a Value for a Pipeline Variable

Keepthefollowingpointsinmindwhenassigningavaluetoapipelinevariable: YoucanonlyassignvaluestovariablesthatareinService InorPipeline Out. IftheService In orPipeline Out variableisalreadythetargetforaLink modifier,you cannotusetheSet Value modifiertoassignavaluetothevariable. YoucanmixliteralvaluesandpipelinevariableswhenassigningvaluestoString variables. YoucannotassignavaluetoarecursiveISdocumenttype(adocumenttypethat containsadocumentreferencetoitself). WhenyousetvaluesforconstrainedObjects,Developerautomaticallyvalidatesthe values.Ifthevalueisnotofthetypespecifiedbytheobjectconstraint,Developer displaysamessageidentifyingthevariableandtheexpectedtype. YoucannotsetvaluesforunconstrainedObjects(Objectsofunknowntype)orfor Objectsconstrainedasabyte[].

208

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

To assign a value to a variable in the pipeline 1 2 3 4 5 Intheeditor,selecttheINVOKEorMAPstepcontainingthevariableyouwantto alter. ClickthePipelinetab. Selectthevariabletowhichyouwanttoassignavalue. Click onthetoolbar.

IntheInputFordialogbox,specifythevalueyouwanttoassigntothisvariable.

Ifyouwanttoassignaliteralvaluetothevariable,typethatvalue.Thevaluemust beofthesamedatatypeasthevariable. IfyouwanttoderivethevaluefromaStringvariableinthepipeline,typethe nameofthatvariableenclosedin%symbols(forexample,%Phone%).Thenselect thePerform variable substitution checkbox.

Ifyouwanttheservertousethespecifiedvalueonlyifthevariabledoesnotcontaina valueatruntime,cleartheOverwrite pipeline valuecheckbox.(Ifyouselectthischeck box,theserverwillalwaysapplythespecifiedvalue.)

Copying Set Values Between Variables

Youcancopythesetvalueassignedtoavariabletoothervariablesofthesamedatatype inService InorPipeline Out.Whenyoucopysetvaluesfromonepipelinevariableto another,keepthefollowingpointsinmind: Youcanonlycopyandpastesetvaluesbetweenvariablesofthesamedatatype.For example,youcanonlycopythesetvalueassignedtoaStringvariabletoanother Stringvariable. Youcanonlycopyandpastesetvaluesbetweenvariablesifthetargetvariablehasthe samestructureasthesourcevariableorhasnodefinedstructure.Forexample,you cancopythesetvalueofaStringlistvariablewithlength3toanotherStringlist variableonlyifthetargetStringlistalsohaslength3orhasanundefinedlength(no definedstructure). Ifyouarecopyingasetvaluebetweendocumentvariables,thesourcedocument variableandthetargetdocumentvariablemusthavethesamestructureorthetarget documentvariablemusthavenostructuredefined.Forexample,ifthesource documentvariablecontainsthreeStringvariablesnamedCity,State,andZipas children,thetargetdocumentvariablemusthavethreeStringvariablesnamedCity, State,andZipaschildren.

webMethods Developer Users Guide Version 7.1.1

209

8 Mapping Data in a Flow Service

To copy a set value 1 2 3 4 5 Intheeditor,selecttheINVOKEorMAPstepcontainingthevariablewiththevalue youwanttocopyandpaste. ClickthePipelinetab. Selectthe youwanttocopy.

RightclickandselectCopy. Selectthevariableorvariablestowhichyouwanttoassignthecopiedvalue, rightclickandselectPaste. Note: YoucanonlycopyandpastevaluesforvariablesthatareinService InorPipeline Out. Note: Youcanonlypastethesetvalueifthetargetvariableisthesamedatatypeasthe sourcevariableandifthetargetvariablehaseitheranidenticalstructuretothesource variableorhasnodefinedstructure.

Dropping Variables from the Pipeline

TheDrop pipelinemodifierallowsyoutoremoveavariablefromPipeline InorPipeline Out.Youcanuseittoeliminatepipelinevariablesthatarenotusedbysubsequent servicesinaflow.Droppingunneededvariablesreducesthesizeofthepipelineatrun timeandreducesthelengthandcomplexityofthePipeline InandPipeline Outdisplays(this canmakethePipelinetabmucheasiertousewhenyouareworkingwithacomplexflow). Important! Onceyoudropavariablefromthepipeline,itisnolongeravailableto subsequentservicesintheflow.DonotusetheDropmodifierunlessyouaresurethe variableisnotusedbyservicesinvokedafterthepointwhereyoudropit. Atruntime,theserverremovesadroppedvariablefromthepipelinejustbeforeit executestheselectedservice(ifyouattachtheDropmodifiertoavariableinPipeline In)or immediatelyafteritexecutestheselectedservice(ifyouattachtheDropmodifiertoa variableinPipeline Out). IfyoudropalinkedvariablefromPipeline In,theserverexecutestheLinkmodifierbeforeit dropsthevariable.Theserverdoesnotlinkanullvaluetothedestinationvariable.

210

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

To drop a variable from the pipeline 1 2 3 4 Intheeditor,selecttheINVOKEorMAPstepwhosepipelinevariablesyouwantto drop. ClickthePipelinetab. Selectthevariablethatyouwanttodrop. Click onthetoolbar.

Note: YoucanonlydropvariablesfromPipeline InandPipeline Out.InaMAPstep,you canonlydropvariablesfromPipeline In.

Adding Variables with the Pipeline Tab

YoucanusethePipelinetabtoaddvariablesthatwerenotdeclaredasinputoroutput parametersfortheflowserviceitselforanyofitsconstituentservices.Youcanuseitto addvariablesthatwereomittedfromaservicesinputoroutputparametersorcreate temporaryvariablesforusewithintheflow.(Forexample,youmightattachavariableto eachofthechildreninaBRANCHsteptomarkthepathtakenbytheserviceatruntime.) VariablesthatyoucreateusingthePipelinetabcanbeusedjustlikeanydeclaredvariable intheflow. Important! Ifyoucreateanewvariableinaflow,youmustimmediatelydooneofthe following: Linkavariabletoit Assignavaluetoit Dropit Ifyoudonottakeoneofthesesteps,Developerautomaticallyclearsitfromthe Pipelinetab. Note: Youmightwanttodropavariableimmediatelyafteraddingitifaservice producesavariablethatisnotdeclaredintheserviceinputoroutputparameters.The variablewillnotappearonthePipelinetabifitisnotaninputoroutputparameter.By addingandthenimmediatelydroppingthevariable,youcandeletethevariableifit doesexistinthepipeline.

webMethods Developer Users Guide Version 7.1.1

211

8 Mapping Data in a Flow Service

To add a variable to the pipeline 1 2 3 Intheeditor,selecttheINVOKEorMAPstepthatrepresentsthestageofthepipeline atwhichyouwanttoaddanewvariable. ClickthePipelinetab. Selectthepointwhereyouwanttoaddthenewvariable. Note: InanINVOKEstep,youcanaddanewvariabletoPipeline In,Service In, Service Out,orPipeline Out.InaMAPstep,youcanonlyaddnewvariablesin Pipeline Out. 4 5 6 Click andselectthetypeofvariablethatyouwanttocreate.

TypethenameofthevariableandpressENTER. Ifthevariableisadocumentoradocumentlist,repeatsteps 4and5todefineits membervariables.Thenuse toindenteachmembervariablebeneaththe documentordocumentlistvariable.

Assignoneofthepipelinemodifierstothenewvariable(Link,Drop,orSet Value).(If youdonotassignamodifiertothevariable,Developerconsidersitextraneoustothe flowandautomaticallyclearsthevariablewhenitrefreshesthePipelinetab.)

Working with Transformers

BylinkingvariablestoeachotheronthePipelinetab,youcanaccomplishname transformationsandstructuraltransformations.However,toperformvalue transformationsyoumustexecutesomecodeorlogic(thatis,youmustinvokeaservice). Developerprovidestwowaysforyoutoinvokeservices:YoucaninsertINVOKEstepsor youcaninserttransformersontothePipelinetab.

What Are Transformers?

TransformersaretheservicesyouusetoaccomplishvaluetransformationsonthePipeline tab.YoucanonlyinsertatransformerintoaMAPstep.Youcanuseanyserviceasa transformer.ThisincludesanyJava,Corflowservicethatyoucreateandanybuiltin servicesinWmPublic,suchasthepub.date.getCurrentDateStringandthepub.string.concat services.Byusingtransformers,youcaninvokemultipleservices(andperformmultiple valuetransformations)inasingleflowstep. Note: ServicesthatyouinsertusingtheINVOKEstepmightalsoperformvalue transformations.However,onlytransformerscanaccomplishmultiplevalue transformationsinasingleflowstep.

212

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

YoucanthinkoftransformersasaseriesofINVOKEstepsembeddedinaMAPstep.And likeINVOKEsteps,whenyouinsertatransformer,youneedtocreatelinksbetween pipelinevariablesandthetransformer.Youcanalsosetpropertiesforthetransformer andvalidatetheinputand/oroutputofthetransformer.Becausetransformersare containedwithinaMAPstep,theydonotappearasaseparateflowstepintheeditor. Transformersarewellsuitedforusewhenmappingdatafromonedocumentformatto another.Whenyoumapdatabetweenformats,youusuallyneedtoperformseveral name,structure,andvaluetransformations.Byusingtransformers,theflowservicein whichyoumapdatabetweenformatscouldpotentiallyconsistofasingleMAPstepin wheretransformersandlinksbetweenvariableshandleallofthedatatransformations.In thisway,youcouldseeyourentiredocumenttodocumentmappinginasingleview. Tip! Youcancreateaflowservicethatusestransformerstoconvertdatabetween documentformats(suchasanIDOCtoanXMLdocumentorRosettaNetPIPtoa proprietaryformat).Youcouldtheninvokethisserviceinotherflowserviceseach timeyouneedtoconvertbetweenthespecificdocumentformatsbeforeyoubegin processingdata. MAP step with transformers

Note: InaMAPstep,Developeronlydisplaysthelinksbetweenpipelinevariablesand transformers.DeveloperdoesnotdisplayanyimplicitlinkingforaMAPstep.

webMethods Developer Users Guide Version 7.1.1

213

8 Mapping Data in a Flow Service

Using Built-in Services as Transformers

AnyserviceintheNavigationpanelcanbeusedasatransformer.webMethods IntegrationServerprovidesseveralbuiltinservicesspecificallydesignedtotranslate valuesbetweenformats.Theseservicescanbefoundinthefollowingfoldersinthe WmPublicpackage: This folder pub.date pub.document pub.list pub.math pub.string Contains services to Transformtimeanddateinformationfromoneformattoanother. TransformdocumentstoandfromdocumentlistsandXMLvalues. TransformaStringlisttoadocumentlist(IData[]object)and appenditemstoadocumentlist(IData[]object)oraStringlist. Performsimplearithmeticcalculations(add,subtract,multiply,and divide)onintegersanddecimalscontainedinstringvariables. Transformstringvaluesinvariousways(forexample,pad, substring,concat,replacethroughalookuptable).

Formoreinformationaboutbuiltinservices,seethewebMethodsIntegrationServerBuilt InServicesReference.

Inserting a Transformer into a MAP Step

Whenyouinsertatransformer,youareessentiallyinsertinganINVOKEstepintoaMAP step.Wheninsertingtransformers,keepthefollowingpointsinmind: TransformerscanonlybeinsertedinaMAPstep. Anyservicecanbeusedasatransformer,includingflowservices,Cservices,and Javaservices. ThetransformersyouinsertintoaMAPstepoperateonthesamesetofpipelinedata. Theoutputofonetransformercannotbeusedastheinputofanothertransformerin thesameMAPstep. TransformersinaMAPstepareindependentofeachotheranddonotexecuteina specificorder.Wheninsertingtransformers,assumethatwebMethodsIntegration Serverconcurrentlyexecutesthetransformersatruntime. To insert a transformer 1 2 3 Intheeditor,selecttheMAPstepinwhichyouwanttoinsertatransformer. ClicktheTransformersareaonthePipelinetab. Click onthePipelinetabtoolbarandthenselecttheserviceyouwanttoinvoke. Iftheserviceyouwanttoinsertdoesnotappearinthelist,selectBrowsetoselectthe

214

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

servicefromtheNavigationpanel.ThetransformerappearsunderTransformers onthe Pipelinetab. 4 Selectthetransformerand,inthePropertiespanel,setitsproperties: For this property... Service Specify... Thefullyqualifiednameoftheservicethatwillbeinvokedat runtimeasatransformer.Whenyouinsertatransformer, Developerautomaticallyassignsthenameofthatserviceto theserviceproperty.Ifyouwanttochangetheservicethatis invokedbyatransformer,specifytheservicesfullyqualified nameinthefolderName:serviceNameformatorclick toselect aservicefromalist. Whetherornotyouwanttovalidatetheinputtothe transformeragainstthesignatureoftheservice.SelectTrueto validatetheinputofthetransformer.SelectFalseifyoudonot wanttovalidatetheinputofthetransformer. Forinformationaboutvalidatingtransformers,seeValidating InputandOutputforTransformersonpage 218. Validate output Whetherornotyouwanttovalidatetheoutputofthe transformeragainstthesignatureoftheservice.SelectTrueto validatetheoutputofthetransformer.SelectFalseifyoudo notwanttovalidatetheoutputofthetransformer. Forinformationaboutvalidatingtransformers,seeValidating InputandOutputforTransformersonpage 218. 5 ClickOK. Forinformationaboutdebuggingtransformers,seeDebuggingTransformerson page 222. Tip! WhenyouexpandatransformerintheTransformersareaofthePipelinetab,you canseetheService InvariablesandtheService Out variablesandalloftheexplicitlinks betweenthetransformerandthepipeline.Youmightfinditeasiertolinktransformer variableswhenyouarezoomedinonthetransformer.

Validate input

Linking Variables to a Transformer

Whenyoumapdatatoandfromatransformer,youcreatelinksbetweenthepipeline variablesandthetransformer.Keepthefollowingpointsinmindwhenyoucreatelinks betweenpipelineandtransformervariables: Developerdoesnotimplicitlylinkpipelinevariablestotheinputoroutputvariables ofatransformer.Evenifthepipelinevariableshavethesamenameanddatatypeas thetransformervariables,noimplicitlinkingoccurs.Youneedtoexplicitlylink pipelinevariablestotheinputandoutputvariablesofatransformer.

webMethods Developer Users Guide Version 7.1.1

215

8 Mapping Data in a Flow Service

Outputforatransformerisnotautomaticallyaddedtothepipeline.Ifyouwantthe outputofatransformertoappearinthepipeline,youneedtoexplicitlylinkthe outputvariabletoaPipeline Outvariable.Ifyoudonotlinktheoutputvariabletoa Pipeline Outvariable,theoutputvariabledoesnotappearinthepipeline. Ifyoudonotlinkanyoutputvariablesorthetransformerdoesnothaveanydeclared outputvariables,thetransformerservicewillnotrun. ThetransformersyouinsertintoasingleMAPstepactonthesamesetofpipeline data. Toprovidethecleanestandsimplestviewwhenworkingwithtransformers,thePipeline tabonlydisplaysonelinkbetweenthetransformerandaPipeline In variableandonelink betweenthetransformerandaPipeline Outvariable.(ThePipelinetabdisplaysthelinks betweenthetransformerandthehighestpositionedPipeline InvariableandPipeline Out variabletowhichthetransformerislinked.) To create a link between a pipeline variable and a transformer 1 TocreatealinkbetweenaPipeline Invariableandatransformervariable,dothe following: a b InPipeline In,selectthevariableyouwanttouseasinputtothetransformerand dragyourmousetothetransformer. IntheLink Tolist,selectthetransformervariabletowhichyouwanttolinkthe Pipeline Invariable. OnceyoulinkatransformerinputvariabletoaPipeline Invariable,Developer displaysthephrasehasalreadybeenchosennexttothetransformervariablein theLink Tolist. c Repeatsteps aandbforeachtransformerinputvariableyouwanttolinktoa pipelinevariable. Note: YoucanassignavaluetoatransformerinputvariableusingtheSet Value modifier .Toassignaninputvaluetoatransformer,firstexpandthe transformerbydoubleclickingthetransformername,byclicking ComposeExpand,orbyclicking nexttothetransformer. 2 TocreatealinkbetweenatransformeroutputvariableandaPipeline Outvariable,do thefollowing: a b c SelectthetransformeranddragyourmousetothevariableinPipeline Outtowhich youwanttolinkthetransformervariable. IntheLink Fromlist,selectthetransformervariablethatyouwanttolinktothe selectedPipeline Outvariable. Repeatsteps aandbforeachoutputvariableproducedbythetransformer. YoucanlinkatransformeroutputvariabletomorethanonePipeline Outvariable.

216

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Important! Developerdoesnotautomaticallyaddtheoutputofatransformertothe pipeline.Ifyouwanttheoutputofatransformertoappearinthepipelineafterthe transformerexecutes,youneedtoexplicitlylinktheoutputvariabletoavariablein Pipeline Out. Important! Ifyoudonotlinkanyoutputvariablesorthetransformerdoesnothaveany outputvariables,thetransformerwillnotexecute.

Transformer Movement
Whenyoulinktoandfromaselectedtransformer,itmovesupanddowninthe Transformerscolumn.Thismovementorjumpingisbydesigntohelpminimizethe distancebetweenthetransformerandthevariableyouarelinkingitto. Transformersexhibitthefollowingbehaviorormovement: WhenatransformerisselectedandyouselectavariableinPipeline InorPipeline Out, thetransformerjumpsormovesupordownintheTransformerscolumnsothatitis directlyacrossfromtheselectedpipelinevariable. Whenyoufinishlinkingatransformeranditisnolongerselected,Developer anchorsoralignsthetransformernexttothehighestPipeline Outvariableitislinked to. Tostopthetransformerfromjumping,clickthetransformeragainorclickintheempty areasofthePipelinetab. Note: ToexpandyourviewofthePipelinetab,dragthemovableborderabovethetab. ThePipelinetabexpandstofitintheDeveloperwindow.

Transformers and Array Variables

Whencreatinglinksbetweenpipelinevariablesandtransformers,differencesin dimensionalityforthesourceandtargetvariablesmaycauseanexception.Ifthe dimensionalityofthetargetvariableisgreaterthanthedimensionalityofthesource variable,anexceptionwillnotbethrown.However,ifthedimensionofthesource variableisgreaterthanthedimensionofthetargetvariable,anexceptionwilloccur. What Is Dimensionality? Dimensionalityreferstothenumberofarraystowhichavariablebelongs.Forexample, thedimensionalityofasingleStringis0,thatofasingleStringlistordocumentlistis1, andthatofasingleStringtableis2.AStringthatisachildofadocumentlisthasa dimensionalityof1.AStringlistthatisachildofadocumentlisthasadimensionality of 2.

webMethods Developer Users Guide Version 7.1.1

217

8 Mapping Data in a Flow Service

Example Inthefollowingexample,theunitPricevariablecannotbelinkedtonum1becausethe unitPricevariablehasadimensionalityof1(string(0)+documentlist(1)=1)andnum1 hasadimensionof0. unitPrice cannot be linked to num1 because of dimensionality differences

Solution Tosolvethis,youcaneither: Changetheserviceinvokedbythetransformertoacceptarraysasdata,or CreateaflowserviceinwhichaLOOPsteploopsoverthearrayvariable.Then,(in thesameflowservice)invoketheserviceyouoriginallywantedtouseasa transformer,andmakethatINVOKEstepachildoftheLOOP.Finally,insertthe resultingflowserviceasatransformerintheMAP. Ofthetwooptions,changingtheservicetoacceptarraysasdataresultsinfaster executionofflowservices.

Validating Input and Output for Transformers

AswithanyserviceyouinsertusinganINVOKE,youcanvalidatetheinputsand outputsofthetransformerservicebeforeand/orafteritexecutes.Toindicatethatyou wanttovalidateatransformersinputsandoutputs,youchangethepropertiesofthe transformer.Youdonothavetousevalidationforallofthetransformersyouinsertintoa MAPstep. Whentheservervalidatesatransformersinputsandoutputsatruntime,itvalidatesthe transformeragainsttheinputandoutputparametersoftheinvokedservice.Toviewthe inputandoutputparametersoftheinvokedservice,opentheserviceandthenclickthe servicesInput/Outputtab.Thevariablesontheinputandoutputsidesofthetabrepresent thedeclaredparametersfortheservice.Toviewtheconstraintsplacedonavariable,click thevariableandviewitsConstraintspropertiesinthePropertiespanel.

218

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Note: IftheValidate inputand/orValidate outputpropertiesoftheinvokedserviceareset toTrue,theinputand/oroutputfortheservicewillautomaticallybevalidatedevery timetheserviceisexecuted.Ifyousetupvalidationviathepropertiesfora transformerwhenitisalreadysetupforvalidationviatheservicesPropertiespanel, thenyouareperformingvalidationtwice.Thiscanslowdowntheexecutionofa transformerand,ultimately,theflowservice. To validate the input and output of a transformer 1 2 3 4 Intheeditor,selecttheMAPstepcontainingthetransformeryouwanttovalidate. ClickthePipelinetab. UnderTransformers,selectthetransformerforwhichyouwanttovalidateinputor output. OnthePropertiespanel,fortheValidate inputproperty,selectTrueifyouwantto validatetheinputtothetransformeragainsttheinputparametersoftheinvoked service. FortheValidate outputproperty,selectTrueifyouwanttovalidatetheoutputofthe transformeragainsttheoutputparametersoftheinvokedservice. ClickOK.

5 6

Copying Transformers
YoumaywanttousethesametransformermorethanonceinaMAPstep.Forexample, youmightwanttoconvertallthedatesinapurchaseordertothesameformat.Insteadof usingthe buttontolocateandselecttheservice,youcancopyandpastethe transformerservice. YoucanalsocopytransformersbetweenMAPstepsinthesamefloworMAPstepsin differentflowservices. Important! Copyingatransformerdoesnotcopythelinksbetweentransformer variablesandpipelinevariablesoranyvaluesyoumighthaveassignedto transformervariablesusingtheSet Valuemodifier. To copy a transformer 1 2 3 Intheeditor,selecttheMAPstepcontainingthetransformerserviceyouwantto copy. ClickthePipelinetab. UnderTransformers,selectthetransformerserviceyouwanttocopy.Rightclickthe transformerandthenselectCopy.

webMethods Developer Users Guide Version 7.1.1

219

8 Mapping Data in a Flow Service

4 5

Topastethetransformer,clickanywhereunderTransformers.Rightclickandselect Paste. Linktheinputandoutputvariablesofthetransformerusingtheprocedures describedinLinkingVariablestoaTransformeronpage 215.

Expanding Transformers
Youmightfinditeasiertocreatelinkstotransformerswhenyouexpandthetransformer. Whenyouexpandatransformer,youcanseetheService InandtheService Outvariables forthetransformerandallofthelinksbetweenthepipelineandthetransformer variables. Pipeline tab with an expanded transformer

Whenyouexpandatransformer,youcanonlyperformactionsforthattransformer,for example,youcanonlylinkvariablesorsetpropertiesfortheexpandedtransformer. Othertransformersandlinkstoothertransformersremainhiddenuntilyoucollapsethe transformer. Note: Ifyouexpandatransformer,youcanusetheSet Valuemodifiertoassignavalue toavariableinService In. To expand and collapse the contents of a transformer Toexpandthecontentsofatransformer,clickComposeExpand. Tocollapsethecontentsofatransformer,clickComposeCollapse. Tip! Youcanalsoexpand/collapseatransformerbydoubleclickingit.

220

webMethods Developer Users Guide Version 7.1.1

8 Mapping Data in a Flow Service

Note: IfIntegrationServerdisplaysamessagestatingthatthetransformercannot befound,thentheserviceinvokedbythetransformerhasbeenrenamed,moved, ordeleted.Youmustusethetransformerpropertiestorenamethetransformer. Seethefollowingsectionformoreinformation.

Renaming Transformers
IfIntegrationServerdisplaysthemessageTransformernotfoundwhenyoutryto expandatransformerorwhenyoupointthemousetothetransformer,thentheservice referencedbythetransformerhasbeenrenamed,moved,ordeleted.Youneedtochange theServicepropertyofthetransformersothatthetransformerpointstothemoved,or renamedservice. Iftheservicereferencedbythetransformerhasbeendeleted,youmaywanttodeletethe transformer. Tip! Youcanenablesafeguardssothatyoudonotinadvertentlyaffectorbreakother serviceswhenyoumove,rename,ordeleteaservice.Formoreinformation,see SpecifyingDependencyCheckingSafeguardsonpage 43. To rename a transformer 1 2 3 4 UsetheNavigationpaneltodeterminethenewnameorlocationoftheservicecalled bythetransformer. Opentheflowservicecontainingthetransformeryouwanttorename. Intheeditor,selecttheMAPstepcontainingthetransformer.Then,onthePipelinetab, selectthetransformeryouwanttorename. IntheServicepropertyonthePropertiespanel,deletetheoldnameandtypeinthe servicesnewfullyqualifiednameinthefolderName:serviceNameformat,orclick to selectaservicefromalist.

webMethods Developer Users Guide Version 7.1.1

221

8 Mapping Data in a Flow Service

Debugging Transformers
Whenyoutestanddebugaflowservice,youcanusethefollowingtestingand debuggingtechniqueswithtransformers: StepintoaMAPstepandstepthroughtheexecutionofeachtransformer.Formore informationaboutsteppingintoandoutofaMAPstep,seeUsingtheStepTools withaMAPSteponpage 288. Setabreakpointonatransformersothatserviceexecutionstopswhenthe transformerisencountered.Formoreinformationaboutsettingbreakpoints,see SettingBreakpointsonpage 288. Disableatransformersothatitdoesnotexecuteatruntime.Formoreinformation aboutdisablingtransformers,seeDisablingTransformersonpage 293.

222

webMethods Developer Users Guide Version 7.1.1

Creating IS Schemas, IS Document Types, and Specifications

224 233 248

Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

223

9 Creating IS Schemas, IS Document Types, and Specifications

Creating an IS Schema
AnISschemaisafreestandingelement intheNavigationpanelthatactsasthe blueprintormodelagainstwhichyouvalidateanXMLdocument.TheISschema providesaformaldescriptionofthestructureandcontentforavalidinstancedocument (theXMLdocument).Theformaldescriptioniscreatedthroughthespecificationof constraints.AnISschemacancontainthefollowingtypesofconstraints: Structural constraintsinanISschemadescribetheelements,attributes,andtypesthat appearinavalidinstancedocument.Forexample,anISschemaforapurchaseorder mightspecifythatavalid<lineItem>elementmustconsistofthe<itemNumber>, <size>,<color>,<quantity>,and<unitPrice>elementsinthatorder. Content constraints inanISschemadescribethetypeofinformationthatelementsand attributescancontaininavalidinstancedocument.Forexample,the<quantity> elementmightberequiredtocontainavaluethatisapositiveinteger. Duringdatavalidation,thevalidationengineinwebMethodsIntegrationServer comparestheelementsandattributesintheinstancedocumentwiththestructuraland contentconstraintsdescribedforthoseelementsandattributesintheISschema.The validationengineconsiderstheinstancedocumenttobevalidwhenitcomplieswiththe structuralandcontentconstraintsdescribedintheISschema.Formoreinformation aboutdatavalidation,seeChapter 10,PerformingDataValidation. YoucancreateISschemasfromanXMLSchema,aDTD(DocumentTypeDefinition),or anXMLdocumentthatreferencesanexistingDTD.ForinformationaboutcreatingIS schemas,seeCreatinganISSchemaonpage 229.

What Does an IS Schema Look Like?

TheappearanceandcontentofanISschemadependsonwhetheryougenerateanIS schemafromanXMLSchemaoraDTD.Forexample,ifyoucreateanISschemafroman XMLSchema,theresultingISschemadisplaystypedefinitions,elementdeclarations, andattributedeclarations.IfyoucreateanISschemafromaDTD,theresultingISschema displayselementtypedeclarations. WhenyouselectanISschemaintheNavigationpanel,Developerdisplaysthecontents oftheISschemaintheeditor.Theschemaeditorisdividedintotwoareas:theschema browserontheleftandtheschemadetailsareaontheright.Abovetheseareas,theeditor identifiesthetargetnamespacefortheISschema.

224

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Schema editor
Specifies the target namespace to which the schema belongs.

Select a component in the schema browser...

...to view and/or edit the component in the schema details area.

Schema Browser
TheschemabrowserdisplaysthecomponentsofanISschemainaformatthatmirrors thestructureandcontentofthesourcefile.Theschemabrowsergroupstheglobal elementdeclarations,attributedeclarations,simpletypedefinitions,andcomplextype definitionsfromthesourcefileunderthetoplevelheadingsELEMENTS,ATTRIBUTES, SIMPLETYPES,andCOMPLEXTYPES.Forexample,theELEMENTSheadingcontains alloftheglobalelementdeclarationsfromtheXMLSchemaortheDTD. Ifthesourcefiledoesnotcontainoneoftheseglobalcomponents,thecorresponding headingisabsent.Forexample,ifyoucreateanISschemafromanXMLSchemathat doesnotcontainanyglobalattributedeclarations,theschemabrowserdoesnotdisplay theATTRIBUTESheading.AnISschemacreatedfromaDTDneverdisplaystheSIMPLE TYPESorCOMPLEXTYPESheadingsbecauseDTDsdonotcontaintypedefinitions. Note: ADTDdoescontainattributedeclarations.However,theschemabrowserdoes notdisplaytheATTRIBUTESheadingforISschemasgeneratedfromDTDs.Thisis becauseanattributedeclarationinaDTDassociatestheattributewithanelement type.Accordingly,theschemabrowserdisplaysattributesaschildrenoftheelement typedeclarationtowhichtheyareassigned.Formoreinformation,seethe webMethodsIntegrationServerSchemaReference. TheschemabrowserusesuniquesymbolstorepresentthecomponentsoftheISschema. EachofthesesymbolsrelatestoacomponentofanXMLSchemaoraDTD.Thefollowing tableidentifiesthesymbolforeachcomponentthatcanappearinanISschema.

webMethods Developer Users Guide Version 7.1.1

225

9 Creating IS Schemas, IS Document Types, and Specifications

Note: Inthefollowingtable,globalreferstoelements,attributes,andtypesdeclaredor definedasimmediatechildrenofthe<schema>elementinanXMLSchema.All elementtypedeclarationsinaDTDareconsideredglobaldeclarations. Symbol Description Element declaration.Anelementdeclarationassociatesanelementnamewith atypedefinition.Thissymbolcorrespondstothe<element>declarationin anXMLSchemaandtheELEMENTdeclarationinaDTD. Element reference.Anelementreferenceisareferencefromanelement declarationinacontentspecificationtoagloballydeclaredelement. InanISschemageneratedfromanXMLSchema,thissymbolcorresponds totheref="globalElementName"attributeinan<element>declaration. InanISschemageneratedfromDTD,thissymbolappearsnexttoan elementthatisachildofanotherelement.Theparentelementhasonly elementcontent. Any element declaration. InXMLSchema,an<any>elementdeclarationisa wildcarddeclarationusedasaplaceholderforoneormoreundeclared elementsinaninstancedocument. InaDTD,anelementdeclaredtobeoftypeANYcancontainany wellformedXML.Thissymbolcorrespondstoanelementdeclaredtobeof typeANY. Becausean<any>elementdeclarationdoesnothaveaname,theschema browserusesAnyasthenameoftheelement. Attribute declaration.Anattributedeclarationassociatesanattributename withasimpletypedefinition.ThissymbolcorrespondstotheXMLSchema <attribute>declarationortheattributeinaDTDATTLISTdeclaration. Attribute reference.Anattributereferenceisareferencefromacomplextype definitiontoagloballydeclaredattribute.Thissymbolcorrespondstothe ref="globalAttributeName"attributeinanattributedeclaration. DTDsdonothaveattributereferences.Consequently,attributereferences donotappearinISschemasgeneratedfromDTDs. Any attribute declaration.Ananyattributedeclarationisawildcard declarationusedasaplaceholderforundeclaredattributesinaninstance document.Thissymbolcorrespondstothe<anyAttribute>declarationin anXMLSchema. Becausean<anyAttribute>declarationdoesnotspecifyanattributename, theschemabrowserusesAnyasthenameoftheattribute.

226

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Symbol

Description Simple type definition.Asimpletypedefinitionspecifiesthedatatypefora textonlyelementoranattribute.Unlikecomplextypedefinitions,simple typedefinitionscannotcarryattributes.Thissymbolcorrespondstothe <simpleType>elementinanXMLSchema. Ifthesimpletypedefinitionisunnamed(ananonymoustype),theschema browserdisplaysAnonymousasthenameofthesimpletypedefinition. Complex type definition.Acomplextypedefinitiondefinesthestructureand contentforelementsofcomplextype.(Elementsofcomplextypecan containchildelementsandcarryattributes.)Thissymbolcorrespondsto the<complexType>elementinanXMLSchema. Ifthecomplextypedefinitionisunnamed(ananonymoustype),the schemabrowserdisplaysAnonymousasthenameofthecomplextype definition. Sequence content model. Asequencecontentmodelspecifiesthatthechild elementsintheinstancedocumentmustappearinthesameorderinwhich theyaredeclaredinthecontentmodel.Thissymbolcorrespondstothe <sequence>compositorinanXMLSchemaorasequencelistinanelement typedeclarationinaDTD. Choice content model.Achoicecontentmodelspecifiesthatonlyoneofthe childelementsinthecontentmodelcanappearintheinstancedocument. Thissymbolcorrespondstothe<choice>compositorinanXMLSchemaor achoicelistinaDTDelementtypedeclaration. All content model.Anallcontentmodelspecifiesthatchildelementscan appearonce,ornotatall,andinanyorderintheinstancedocument.This symbolcorrespondstothe<all>compositorinanXMLSchema. Mixed content. Elementsthatcontainmixedcontentallowcharacterdatato beinterspersedwithchildelements.Thissymbolcorrespondstothe mixed="true"attributeinanXMLSchemacomplextypedefinitionora DTDelementlistinwhichthefirstitemis#PCDATA. Empty content.InanXMLSchema,anelementhasemptycontentwhenits associatedcomplextypedefinitiondoesnotcontainanyelement declarations.Anelementwithemptycontentmaystillcarryattributes. InaDTD,anelementhasemptycontentwhenitisdeclaredtobeoftype EMPTY.

webMethods Developer Users Guide Version 7.1.1

227

9 Creating IS Schemas, IS Document Types, and Specifications

Schema Details Area

Theschemadetailsareadisplaysinformationthatyouusetoexamineandeditthe selectedcomponentintheschemabrowser.Thecontentsoftheschemadetailsareavary dependingonwhatcomponentyouselect.Forexample,whenyouselectaglobally declaredelementofcomplextype,theschemadetailsarealookslikethefollowing. Schema details area for a global element declaration of complex type

If you select an element declaration...

... the schema details area displays information about that element.

Whenyouselectasimpletypedefinition,theschemadetailsarealookslikethefollowing: Schema details area for a simple type definition

If you select a simple type definition...

... the schema details area displays fields for viewing/editing the simple type.

228

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Creating an IS Schema
InDeveloper,youcancreateISschemasfromXMLSchemadefinitions,DTDs,andXML documentsthatreferenceanexistingDTD.TheresultingISschemacontainsallofthe definedtypes,declaredelements,anddeclaredattributesfromthesourcefile. Note: TheactualworkofcreatinganISschemaisperformedbytheschemaprocessor. TheschemaprocessoristhesubsystemofthewebMethodsIntegrationServerthat compilesanISschemafromasourcefile. Note: YoucanfindsampleXMLSchemadefinitionsinthefollowingdirectory: Developer_directory\samples\xml\xsd.YoucanalsofindXMLSchemadefinitions andDTDsontheWebsitesforthesegroups:(www.w3c.organd www.openapplications.org). To create an IS schema 1 2 3 4 OntheFilemenu,clickNew. IntheNewdialogbox,selectSchema,andthenclickNext. IntheNewSchemadialogbox,nexttoFolder,selectthefolderwhereyouwanttosave theISschema. IntheNamefield,typeanamefortheISschemausinganycombinationofletters, numbers,andtheunderscorecharacter.ClickNext. Important! Ifyouspecifyanamethatusesareservedwordorcharacter, webMethodsIntegrationServerdisplaysanerrormessage.Whenthishappens, useadifferentnameortryaddingaletterornumbertothenametomakeitvalid. Formoreinformationaboutrestrictedcharactersforpackages,folders,and elements,seeAboutElementNamesonpage 41. 5 IntheNewSchemadialogbox,selectoneofthefollowingtospecifythesourceforthe ISschema. Specify... XML DTD XML Schema To... CreateanISschemabasedonanexistingDTDreferencedbyanXML document. CreateanISschemabasedonaDTD. CreateanISschemabasedonanXMLSchemadefinition.

Important! YoucancreateanISschemafromanXMLdocumentonlyiftheXML documentreferencesanexistingDTD.

webMethods Developer Users Guide Version 7.1.1

229

9 Creating IS Schemas, IS Document Types, and Specifications

6 7

ClickNext. IntheEnter the URL or select a local filebox,dooneofthefollowing:

IfyouwanttobasetheISschemaonanXMLdocument,DTD,orXMLSchema definitionthatresidesontheInternet,typetheURLoftheresource.(TheURLyou specifymustbeginwithhttp:orhttps:.) IfyouwanttobasetheISschemaonanXMLdocument,DTD,orXMLSchema definitionthatresidesonyourlocalfilesystem,typethepathandfilename,or click tonavigatetoandselectthefile.

ClickFinish.DevelopergeneratestheISschemausingthedocumentyouspecifiedand displaysitintheeditor. Note: YoumightreceiveerrorsorwarningswhencreatinganISschemafromanXML SchemadefinitionorDTD.Formoreinformationabouttheseerrorsandwarnings, seeAppendix G,ValidationErrorsandExceptions. Note: WhencreatinganISschemafromanXMLSchemadefinition,Developer validatestheschemaanddoesnotcreatetheISschemaiftheXMLSchemadefinition isnotvalid.Formoreinformation,seeISSchemaGenerationErrorsandWarnings onpage 470.

Creating IS Schemas from XML Schemas that Reference Other Schemas

Aschemaauthorcaninserttheelements,attributes,andtypedefinitionsfromanother schemaintotheschematheyarecreating.Aschemaauthormightdothistobreakupa largeXMLSchemaintoseveralsmall,morereusableXMLSchemas.Whenyougenerate anISschemafromanXMLSchemathatreferencesanotherschema,theschemaprocessor eitherincludesalloftheschemacomponentsinasingleISschema,createsmultipleIS schemas,orcreatesnoISschemaatall.Thebehavioroftheschemaprocessordependson themechanismthesourceXMLSchemausestoreferencetheotherschema.The followingmechanismscanbeusedtoreferenceanexternalschema: Include.WhenyougenerateanISschemafromanXMLSchemathatuses<include>to includethecontentsofanexternalschemainthesamenamespace,theresultingIS schemacontainsallofthedefinedtypes,declaredelements,anddeclaredattributes fromthesourceschemaandtheexternalschema.Iftheincluding,orroot,XML Schemareferencesanexternalschemathatdoesnotcontainatargetnamespace declaration,theexternalschemaassumesthetargetnamespaceoftherootschema. Import.WhenyougenerateanISschemafromanXMLSchemathatcontainsan <import>elementtoimportthecontentsofanexternalschemainadifferent namespace,theschemaprocessorcreatesoneISschemapernamespace.Forexample, ifthesourceXMLSchemaimportstwoXMLSchemasfromthesamenamespace,the schemaprocessorcreatesanISschemaforthesourceXMLSchemaandthenasecond ISschemathatincludesthecomponentsfromthetwoimportedXMLschemas.The schemaprocessorassignseachimportedschemathenamethatyouspecifyand appendsanunderscoreandanumbertoeachname.Forexample,ifyoucreateanIS

230

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

schemanamedmySchemafrommySchema.xsd,theschemaprocessorgeneratesan ISschemanamedmySchema_2fortheimportedXMLSchema. Redefine.Schemaauthorscanalsouse<redefine>toincludeandthenredefinetype definitions,modelgroups,andattributegroupsfromanexternalXMLSchemainthe samenamespace.

Editing a Simple Type in an IS Schema

YoucanmodifyasimpletypedefinitioninanISschemawithouteditingthesourceXML Schemadefinition.Youeditasimpletypebyaddingorchangingthevalueofoneormore constrainingfacetsappliedtothesimpletype.Forexample,youcanmodifyasimple typebyaddinganenumeratedvalue,apatternconstraint,orchangingthelength constraint.EditingthesimpletypethroughDeveloperisanalternativetoeditingthe sourceXMLSchemadefinitionandregeneratingtheISschema. Youcaneditanyofthegloballydefinedsimpletypes(thosethatappearunderthe SIMPLETYPESheading)oranonymoussimpletypes(thosedefinedaspartofan elementorattributedeclaration.)Anamedsimpletypethatappearsasachildofan elementorattributeintheschemabrowsercannotbeedited.(Thesesimpletypesare globalsimpletypesusedtodefinetheelementorattributetheyappearunder.)The followingillustrationidentifiesthesimpletypedefinitionsthatyoucanandcannotedit. Editable simple type definitions in an IS schema

The string simple type cannot be edited. This globally defined simple type can be edited. This simple type cannot be edited because it refers to a globally defined simple type. This anonymous simple type can be edited.

webMethods Developer Users Guide Version 7.1.1

231

9 Creating IS Schemas, IS Document Types, and Specifications

Whenmodifyingasimpletypedefinition,keepthefollowingpointsinmind: Changestoasimpletypedefinitionaffecttheelementsandattributesforwhichthe simpletypeisthedefinedtype.Forexample,iftheattributepartNumisdefinedtobe oftypeSKU,changestotheSKUsimpletypedefinitionaffectthepartNumattribute. ChangestoaglobalsimpletypedefinitioninanISschemadonotaffectsimpletypes derivedfromtheglobalsimpletype;thatis,thechangesarenotpropagatedtothe derivedtypesintheISschema. SimpletypesinanISschemacanbeusedascontentconstraintsforfieldsinpipeline validation.Consequently,changestoasimpletypealsoaffecteveryfieldtowhichthe simpletypeisappliedasacontentconstraint. Tip! Youcancreateacustomsimpletypetoapplytoafieldasacontenttype constraint.Formoreinformationaboutcreatingacustomsimpletypeand applyingconstraintstofields,seeSettingConstrainingFacetValueson page 233. ChangestoasimpletypedefinitionaresavedintheISschema.Ifyouregeneratethe ISschemafromtheXMLSchemadefinition,yourchangeswillbeoverwritten. Whenyouedittheconstrainingfacetsappliedtoasimpletypedefinition,youcan onlymaketheconstrainingfacetvaluesmorerestrictive.Theconstrainingfacets cannotbecomelessrestrictive.Formoreinformationaboutsettingvaluesfor constrainingfacets,seeSettingConstrainingFacetValuesonpage 233. Tip! Ifyouwanttoeditcomplextypedefinitions,attributedeclarations,element declarations,orthestructureoftheschema,youneedtoedittheXMLSchemaand thenregeneratetheISschema. To edit a simple type definition 1 2 3 OpentheISschemathatcontainsthesimpletypeyouwanttoedit. Intheschemabrowserareaoftheeditor,selectthesimpletypethatyouwanttoedit. The symbolappearsnexttosimpletypes. Intheschemadetailsarea,specifytheconstrainingfacetsthatyouwanttoapplyto thesimpletype.Formoreinformationaboutconstrainingfacets,seeConstraining Facetsonpage 448. OntheFilemenu,clickSave.

232

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Setting Constraining Facet Values

Youcaneditanyoftheconstrainingfacetvaluesthatappearintheschemadetailsarea whenyouselectaneditablesimpletypedefinitionintheschemabrowser.The constrainingfacetsdisplayedintheschemadetailsareadependontheprimitivetype fromwhichthesimpletypewasderived.Forexample,ifthesimpletypedefinitionis derivedfromstring,theschemadetailsareadisplaystheenumeration,length,minLength, maxLength,pattern,andwhiteSpacefacets.Theschemadetailsareaonlydisplays constrainingfacetvaluessetinthesimpletypedefinition.Itdoesnotdisplay constrainingfacetvaluesthesimpletypedefinitioninheritedfromthesimpletypesfrom whichitwasderived. Youcanviewtheconstrainingfacetvaluessetinthetypedefinitionsfromwhichasimple typewasderivedbyclickingthe Base Constraints button.Baseconstraintsarethe constrainingfacetvaluessetinallthetypedefinitionsfromwhichasimpletypeis derivedfromtheprimitivetypetotheimmediateparenttype.Theseconstraintvalues representthecumulativefacetvaluesforthesimpletype. Whenyouedittheconstrainingfacetsforasimpletypedefinition,youcanonlymakethe constrainingfacetsmorerestrictivetheappliedconstrainingfacetscannotbecomeless restrictive.Forexample,ifthelengthvalueisappliedtothesimpletype,themaxLengthor minLengthvaluescannotbesetbecausethemaxLengthandminLengthfacetsareless restrictivethanlength.

Creating an IS Document Type

AnISdocumenttypecontainsasetoffieldsusedtodefinethestructureandtypeofdata inadocument(IDataobject).YoucanuseanISdocumenttypetospecifyinputoroutput parametersforaserviceorspecification.YoucanalsouseanISdocumenttypetobuilda documentordocumentlistfieldandastheblueprintforpipelinevalidationand document(IDataobject)validation. ISdocumenttypescanprovidethefollowingbenefits: UsinganISdocumenttypeastheinputoroutputsignatureforaservicecanreduce theeffortrequiredtobuildaflow. UsinganISdocumenttypetobuilddocumentordocumentlistfieldscanreducethe effortneededtodeclareinputoroutputparametersortheeffort/timeneededtobuild otherdocumentfields. ISdocumenttypesimproveaccuracy,becausethereislessopportunitytointroducea typingerrortypingfieldnames. ISdocumenttypesmakefuturechangeseasiertoimplement,becauseyoucanmakea changeinoneplace(theISdocumenttype)ratherthaneverywheretheISdocument typeisused.

webMethods Developer Users Guide Version 7.1.1

233

9 Creating IS Schemas, IS Document Types, and Specifications

YoucancreateanISdocumenttypeinthefollowingways: CreateanemptyISdocumenttypeanddefinethestructureofthedocumenttype yourselfbyinsertingfields. CreateanISdocumenttypefromasourcefile,suchasanXMLSchema,DTD,orXML document.ThestructureandcontentoftheISdocumenttypewillmatchthatofthe sourcefile. CreateanISdocumenttypefromaBrokerdocumenttype.

Creating an Empty IS Document Type

WhenyoucreateanemptyISdocumenttype,youinsertfieldstodefinethecontentsand structureoftheISdocumenttype. Note: IfyouintendtomaketheISdocumenttypepublishable,keepinmindthatthe Brokerhasrestrictionsforfieldnames.Ifyoucreateatriggerthatsubscribestothe publishabledocumenttype,anyfiltersthatincludefieldnamescontainingrestricted characterswillbesavedontheIntegrationServeronly.Thefilterswillnotbesavedon theBroker,possiblyaffectingIntegrationServerperformance.Formoreinformation, seethePublishSubscribeDevelopersGuide. To create an empty IS document type 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectDocument Type andclickNext. IntheNewDocumentTypedialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefolderinwhichyouwanttosavetheIS documenttype. IntheNamefield,typeanamefortheISdocumenttypeusinganycombinationof letters,numbers,and/ortheunderscorecharacter.Forinformationabout restrictedcharacters,seeAboutElementNamesonpage 41. ClickNext.

c 4 5 6

UnderSelect a source,selectNonetoindicatethatyouwanttocreateanemptyIS documenttypeinwhichyoudefinethestructureandfields. ClickFinish. ToaddfieldsintheISdocumenttype,dothefollowing: a b Click onthetoolbarandselectthetypeoffieldthatyouwanttodefine.

TypethenameofthefieldandthenpressENTER.

234

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Note: Developerpreventstheinsertionoffieldsnamed_envinanISdocument type.Fordetailsaboutthe_envfield,seeTheEnvelopeFieldonpage 243. c Withthefieldselected,setfieldpropertiesandapplyconstraintsintheProperties panel(optional). Formoreinformationaboutsettingfieldproperties,seeSpecifyingField Propertiesonpage 247.Forinformationaboutapplyingconstraints,see ApplyingConstraintstoVariablesonpage 255. d Ifthefieldisadocumentoradocumentlist,repeatsteps actodefineandsetthe propertiesandconstraintsforeachofitsmembers.Use fieldbeneaththedocumentordocumentlistfield. 7 OntheFilemenu,clickSave. Note: Developerdisplayssmallsymbolsnexttoafieldicontoindicatevalidation constraints.Developeruses toindicateanoptionalfield.Developerusesthe symboltodenoteafieldwithacontentconstraint.Forinformationaboutapplying constraintstofields,seeApplyingConstraintstoVariablesonpage 255. toindenteachmember

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

YoucancreateanISdocumenttypebasedonthestructureandcontentofasourcefile, suchasanXMLSchema,DTD,orXMLdocument.WhenyoubasetheISdocumenttype onasourcefile,DevelopercreatesanISdocumenttypeandanISschema.TheIS documenttypehasthesamestructureandfieldconstraintsasthesourcedocument.The ISschemacontainstheelements,attributes,anddatatypesdefinedintheXMLSchemaor DTD.TheISdocumenttype,whichdisplaysthefieldsandstructureofthesource document,useslinkstotheISschematoobtaincontenttypeinformationaboutnamed simpletypes.

Points to Consider for All Sources

KeepthefollowingpointinmindwhencreatinganISdocumenttypefromanXML Schema,DTD,orXMLdocument: Whencreatingafieldfromanattributedeclaration,theIntegrationServerinsertsthe @symbolatthebeginningofthefieldname.Forexample,anattributenamed myAttributeinthesourcefilecorrespondstoafieldnamed@myAttributeintheIS documenttype.

webMethods Developer Users Guide Version 7.1.1

235

9 Creating IS Schemas, IS Document Types, and Specifications

Points to Consider When Using a DTD As the Source

KeepthefollowingpointinmindwhencreatinganISdocumenttypefromaDTD: TheIntegrationServerassumesthattheDTDisUTF8encoded.IftheDTDisnot UTF8encoded,addtheXMLprologtothetopoftheDTDandexplicitlystatethe encoding.Forexample,foraDTDencodedin88591,youwouldinsertthefollowing atthetopofthedocument: <?xml version="1.0" encoding="8859-1" ?>

Points to Consider When Using an XML Schema As the Source

KeepthefollowingpointsinmindwhencreatinganISdocumenttypefromanXML Schema: BeforecreatingtheISdocumenttypeandtheISschema,IntegrationServervalidates theXMLSchema.IftheXMLSchemadoesnotconformsyntacticallytotheschema forXMLSchemasdefinedinXMLSchemaPart1:Structures,IntegrationServerdoes notcreateanISschemaoranISdocumenttype.Instead,Developerdisplaysanerror messagethatliststhenumber,title,location,anddescriptionofthevalidationerrors withintheXMLSchema. IntegrationServerusestheprefixesdeclaredintheXMLSchemaaspartofthefield names.Fieldnameshavetheformatprefix:elementNameorprefix:@attributeName. IftheXMLSchemadoesnotuseprefixes,theIntegrationServercreatesprefixesfor eachuniquenamespaceandusesthoseprefixesinthefieldnames.IntegrationServer usesnsastheprefixforthefirstnamespace,ns1forthesecondnamespace,ns2 IntegrationServercancreateseparateISdocumenttypesfornamedcomplextypesor expanddocumenttypesinlinewithinonedocumenttype.Formoreinformation,see ExpandingComplexDocumentTypesInlineonpage 237. IntegrationServercancreateonefieldforasubstitutiongrouporcreatefieldsfor everymemberelementinasubstitutiongroup.Formoreinformation,see GeneratingFieldsforSubstitutionGroupsonpage 239.

236

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Expanding Complex Document Types Inline IntegrationServerprocessescomplextypesfromanXMLSchemainoneoftwoways, dependingonanoptionyouselectwhenyoucreateanewISdocumenttype.Onewayis toexpandthecomplextypeasaninlinedocumenttypeintheeditor.Theotherwayis togenerateaseparateISdocumenttypeforeachcomplextypeintheschema,with referencestothosedocumenttypes. 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>

Ifyouselecttheoptiontoexpandcomplextypesinline,theschemaprocessorgenerates thedocumenttypeasfollows.Inthisexample,theschemaprocessorexpandedthe complextypesnameddocumentXanddocumentYinlinewithinthenewISdocumenttype: Complex types expanded inline

Ifyouselecttheoptiontogeneratecomplextypesasseparatedocumenttypes,the schemaprocessorgeneratesthedocumenttypesasfollows.Inthisexample,theschema processorgeneratedthreeISdocumenttypesoneforthecomplextypenamed documentY,oneforthecomplextypenameddocumentX(withareferencetodocumentY), andonefortherootelementeltA(withreferencestodocumentXanddocumentY):

webMethods Developer Users Guide Version 7.1.1

237

9 Creating IS Schemas, IS Document Types, and Specifications

Complex types generated as separate document types

Theschemaprocessorgeneratesallthreedocumenttypesinthesamefolder. Note: Ifthecomplextypeisanonymous,theschemaprocessorexpandsitinlinerather thangenerateaseparatedocumenttype. IftheXMLSchemayouareusingtogenerateanISdocumenttypecontainsrecursive complextypes(thatis,elementdeclarationsthatrefertotheirparentcomplextypes directlyorindirectly),youcanavoiderrorsinthedocumenttypegenerationprocessby selectingtheoptiontogeneratecomplextypesasseparatedocumenttypes.(Selectingthe optiontoexpandcomplextypesinlinewillresultininfinitelyexpandingnested documents.)

238

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Generating Fields for Substitution Groups IntegrationServerprocessessubstitutiongroupelementsinoneoftwoways,depending onthevalueofthewatt.core.schema.generateSubstitutionGroupsproperty: Whenthispropertyissettotrue,theschemaprocessorimportsallsubstitutiongroup members(headelementandsubstitutableelements)asoptionalfields,eventhough theyaredefinedasrequiredelementsintheXMLSchemadefinition. Whenthispropertyissettofalse,theresultingdocumenttypecontainsafieldthat correspondstotheheadelementinthesubstitutiongroup,butdoesnotcontainany elementsformembersofthesubstitutiongroup.Thisisthedefault. Iftheheadelementisdeclaredasabstract,theIntegrationServerdoesnotincludethat elementintheISdocumenttype. To create an IS document type from an XML document, DTD, or XML Schema 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectDocument Type andclickNext. IntheNewDocumentTypedialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefolderinwhichyouwanttosavetheIS documenttype. IntheNamefield,typeanamefortheISdocumenttypeusinganycombinationof letters,numbers,and/ortheunderscorecharacter.Forinformationaboutreserved wordsorcharacters,seeAboutElementNamesonpage 41. ClickNext.

c 4

UnderSelect a source,selectoneofthefollowing: Select... XML DTD XML Schema To... CreateanISdocumenttypethatmatchesthestructureandfieldsin anXMLdocument. CreateanISdocumenttypethatmatchesthestructureandfieldsin aDTD. CreateanISdocumenttypethatmatchesthestructureandfieldsin anXMLSchemadefinition.

ClickNext.

webMethods Developer Users Guide Version 7.1.1

239

9 Creating IS Schemas, IS Document Types, and Specifications

IntheEnter the URL or select a local filebox,dooneofthefollowing:

IfyouwanttobasetheISdocumenttypeonafilethatresidesontheInternet,type theURLoftheresource.(TheURLyouspecifymustbeginwith http:or https:.) IfyouwanttobasetheISdocumenttypeonafilethatresidesonyourlocalfile system,typeinthepathandfilename,orclick file. tonavigatetoandselectthe

Dooneofthefollowingbasedonyourselectioninstep4:

IfyouselectedXML,clickFinish.DevelopergeneratestheISdocumenttypeusing theXMLdocumentyouspecifiedanddisplaysitintheeditor. IfyouselectedDTD,clickNext.Developerpromptsyoutoselecttherootelementof thedocument.SelecttherootelementandclickOK.DevelopergeneratestheIS documenttypeanddisplaysitintheeditor.DeveloperalsogeneratesanIS schemaanddisplaysitintheNavigationpanel. IfyouselectedXML Schema,clickNext anddothefollowing: 1 2 Selecttherootelementofthedocument. SelecttheappropriateoptiontospecifywhetherDevelopershouldprocess complextypesbyexpandingtheminlineintheeditororbygeneratingthem asseparateISdocumenttypes. ClickFinish.DevelopergeneratestheISdocumenttype(s)anddisplaysthem intheeditor.DeveloperalsogeneratesanISschemaanddisplaysitinthe Navigationpanel.

DevelopercreatestheISdocumenttypeandsavesitontheIntegrationServer.Ifyou wanttoaddoreditfieldsintheISdocumenttype,seeCreatinganEmptyIS DocumentTypeonpage 234. Note: YoumightreceiveerrorsorwarningswhencreatinganISdocumenttype fromaDTDorXMLSchemadefinition.Formoreinformationabouttheseerrors andwarnings,seeValidationErrorsonpage 452.

Creating an IS Document Type from a Broker Document Type

IfyourIntegrationServerisconnectedtoaBroker,youcancreateanISdocumenttype fromaBrokerdocumenttype.TheISdocumenttyperetainsthestructure,fields,data types,andpublicationpropertiesdefinedintheBrokerdocumenttype.Fordetailed informationabouthowaBrokerdocumenttypetranslatestoanISdocumenttypeand viceversa,seethePublishSubscribeDevelopersGuide. WhenyoucreateanISdocumenttypefromaBrokerdocumenttype,youessentially createapublishabledocumenttype.ApublishabledocumenttypeisanISdocumenttype withspecificpublishingproperties,suchasstoragetypeandtimetolive.Additionally,a publishabledocumenttypeonanIntegrationServerisboundtoaBrokerdocumenttype.

240

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

AninstanceofapublishabledocumenttypecanbepublishedtoaBrokerorlocally withinanIntegrationServer. ApublishabledocumenttypecanbeusedanywhereanISdocumenttypecanbeused. Forexample,youcanuseapublishabledocumenttypetodefinetheinputoroutput parametersofaservice.AdocumentreferencefieldcanreferenceanISdocumenttypeor apublishabledocumenttype.Youcanuseapublishabledocumenttypeastheblueprint forperformingdocumentorpipelinevalidation. Tip! AnyISdocumenttypecanbemadeintoapublishabledocumenttype.For informationaboutmakingadocumenttypepublishableorsettingpublication properties,seethePublishSubscribeDevelopersGuide. WhenyoucreateanISdocumenttypefromaBrokerdocumenttypethatreferencesother elements,Developerwillalsocreateanelementforeachreferencedelement.The IntegrationServerwillcontainadocumenttypethatcorrespondstotheBrokerdocument typeandonenewelementforeachelementtheBrokerdocumenttypereferences. Developeralsocreatesthefolderinwhichthereferencedelementwaslocated.Developer savesthenewelementsinthepackageyouselectedforstoringthenewpublishable documenttype. Forexample,supposethattheBrokerdocumenttypereferencesadocumenttypenamed addressinthecustomerInfofolder.DeveloperwouldcreateanISdocumenttypenamed addressandsaveitinthecustomerInfofolder.IfafieldintheBrokerdocumenttypewas constrainedbyasimpletypedefinitiondeclaredintheISschemapurchaseOrder,Developer wouldcreatethereferencedISschemapurchaseOrder. AnelementreferencedbyaBrokerdocumenttypemighthavethesamenameasan existingelementonyourIntegrationServer.However,elementnamesmustbeuniqueon theIntegrationServer.Developergivesyoutheoptionofoverwritingtheexisting elementswiththereferencedelements. Important! IfyoudonotselecttheOverwrite existing elements when importing referenced elementscheckboxandtheBrokerdocumenttypereferencesanelementwiththe samenameasanexistingIntegrationServerelement,Developerwillnotcreatethe publishabledocumenttype. Important! Ifyouchoosetooverwriteexistingelementswithnewelements,keepin mindthatdependentsoftheoverwrittenelementswillbeaffected.Forexample, supposetheaddressdocumenttypedefinedtheinputsignatureofaflowservice deliverOrder.OverwritingtheaddressdocumenttypemightbreakthedeliverOrderflow serviceandanyotherservicesthatinvokeddeliverOrder.

webMethods Developer Users Guide Version 7.1.1

241

9 Creating IS Schemas, IS Document Types, and Specifications

To create an IS document type from a Broker document type 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectDocument Type andclickNext. IntheNewDocumentTypedialogbox,dothefollowing: a b c 4 5 InthelistnexttoFolder,selectthefolderinwhichyouwanttosavetheIS documenttype. IntheNamefield,typeanamefortheISdocumenttypeusinganycombinationof letters,numbers,and/ortheunderscorecharacter. ClickNext.

UnderSelect a source,selectBroker Document Type,andclickNext. IntheNewDocumentTypedialogbox,dothefollowing: a IntheBroker Namespacefield,selecttheBrokerdocumenttypefromwhichyou wanttocreateanISdocumenttype.TheBroker Namespacefieldlistsallofthe BrokerdocumenttypesontheBrokerterritorytowhichtheIntegrationServeris connected. IfyouwanttoreplaceexistingelementsintheNavigationpanelwithidentically namedelementsreferencedbytheBrokerdocumenttype,selecttheOverwrite existing elements when importing referenced elementscheckbox. Important! Overwritingtheexistingelementscompletelyreplacestheexisting elementwiththecontentofthereferencedelement.Anyelementsonthe IntegrationServerthatdependonthereplacedelement,suchasflowservices, ISdocumenttypes,andspecifications,mightbeaffected.

ClickFinish.DeveloperautomaticallyrefreshestheNavigationpanelanddisplays besidethedocumenttypenametoindicateitisapublishabledocumenttype. Notes:

YoucanassociateonlyoneISdocumenttypewithagivenBrokerdocumenttype. IfyoutrytocreateapublishabledocumenttypefromaBrokerdocumenttype thatisalreadyassociatedwithapublishabledocumenttypeonyourIntegration Server,Developerdisplaysanerrormessage. InthePublicationcategoryofthePropertiespanel,theBroker doc typeproperty displaysthenameoftheBrokerdocumenttypeusedtocreatethepublishable documenttype.Or,ifyouarenotconnectedtoaBroker,thisfielddisplaysNot Publishable.Youcannoteditthecontentsofthisfield.Formoreinformationabout thecontentsofthisfield,seethePublishSubscribeDevelopersGuide.

242

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

OnceapublishabledocumenttypehasanassociatedBrokerdocumenttype,you needtomakesurethatthedocumenttypesremaininsync.Thatis,changesinone documenttypemustbemadetotheassociateddocumenttype.Youcanupdate onedocumenttypewithchangesintheotherbysynchronizingthem.For informationaboutsynchronizingdocumenttypes,seethePublishSubscribe DevelopersGuide.

The Envelope Field

Allpublishabledocumenttypescontainanenvelope(_env)field.Thisfieldisadocument referencetothepub:publish:envelopedocumenttype.Thisdocumenttypedefinesthe contentandstructureoftheenvelopethataccompaniesinstancesofthepublishable document.Theenveloperecordsinformationsuchasthesendersaddress,thetimethe documentwassent,sequencenumbers,andotherusefulinformationforroutingand control.Theenvelopeismuchlikeaheaderinanemailmessage. Becausethe_envfieldisneededforpublication,Developercontrolstheusageofthe_env fieldinthefollowingways: Youcannotinsertan_envfieldinadocumenttype.Developerautomaticallyinserts the_envfieldattheendofthedocumenttypewhenyoumakethedocumenttype publishable. Youcannotcopyandpastethe_envfieldfromonedocumenttypetoanother.Youcan copythisfieldtotheInput/Output tab. Youcannotmove,rename,orcutthe_envfieldfromadocumenttype.Developer automaticallyremovesthe_envfieldwhenyoumakeadocumenttype unpublishable. Youcanonlydeletean_envfieldfromadocumenttypethatisnotpublishable. The_envfieldisalwaysthelastfieldinapublishabledocumenttype. Formoreinformationaboutthe_envfieldandthecontentsofthepub:publish:envelope documenttype,seethePublishSubscribeDevelopersGuide. Note: IfanISdocumenttypecontainsafieldnamed_env,youneedtodeletethatfield beforeyoucanmaketheISdocumenttypepublishable.

Adapter Notifications and Publishable Document Types

AdapternotificationsnotifywebMethodscomponentswheneveraspecificeventoccurson anadaptersresource.Theadapternotificationpublishesadocumentwhenthespecified eventoccursontheresource.Forexample,ifyouareusingtheJDBCAdapteranda changeoccursinadatabasetablethatanadapternotificationismonitoring,theadapter notificationpublishesadocumentcontainingdatafromtheeventandsendsittothe IntegrationServer. Anadapternotificationcanhaveanassociatedpublishabledocumenttype .When youcreateapollingorasynchronouslisteneradapternotificationinDeveloper,the

webMethods Developer Users Guide Version 7.1.1

243

9 Creating IS Schemas, IS Document Types, and Specifications

IntegrationServerautomaticallygeneratesacorrespondingpublishabledocumenttype. Developerassignsthepublishabledocumenttypethesamenameastheadapter notification,butappendsPublishDocumenttothename.Thatis,Developerassignsthe publishabledocumenttypethename:NotificationNamePublishDocument.Youcanuse thispublishabledocumenttypewithtriggersandflowservicesjustasyouwouldany otherpublishabledocumenttype. Inapublishabledocumenttypeassociatedwithanadapternotification,youcaneditonly theStorage typeandTime to livepublicationproperties.Tomakeanyothermodificationsto thepublishabledocumenttype,youmustmodifytheadapternotificationtype. IntegrationServerautomaticallyappliesthechangestothepublishabledocumenttype. Forinformationaboutpublicationproperties,seethePublishSubscribeDevelopersGuide. Formoreinformationaboutcreatingandusingadapternotifications,seetheappropriate adapteruserguide.Formoreinformationaboutperformingactionsonadapter notificationsandtheirassociatedpublishabledocumenttypes,seeChapter 2,Managing ElementsintheNavigationPanel.

Editing an IS Document Type

WhenyoumakeachangetoanISdocumenttype,keepinmindthatanychangeis automaticallypropagatedtoallservices,specifications,documentfields,anddocument listfieldsthatuseorreferencetheISdocumenttype.(Thishappenswhenyousavethe updatedISdocumenttypetotheserver.)YoucanusetheToolsFind Dependents commandtoviewalistofelementsthatusetheISdocumenttypeandwillbeaffectedby anychanges. Important! IfyouuseanISdocumenttypeastheblueprintforpipelineordocument validation,anychangesyoumaketotheISdocumenttypecanaffectwhetherthe objectbeingvalidated(pipelineordocument)isconsideredvalid.Formore informationaboutvalidation,seeChapter 10,PerformingDataValidation.

Modifying Publishable Document Types

Whenyoumodifyapublishabledocumenttype,suchasbydeletingafieldorchanginga property,thepublishabledocumenttypeisnolongersynchronizedwiththe correspondingdocumenttypeontheBroker.Whenyousaveyourchangestothe publishabledocumenttype,Developerdisplaysamessagestating:
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.

DeveloperdisplaysthismessageonlyifaBrokerisconfiguredfortheIntegrationServer. ToupdatetheassociatedBrokerdocumenttypewiththechanges,synchronizethe publishabledocumenttypewiththeBrokerdocumenttype.Formoreinformationabout synchronizingdocumenttypes,seethePublishSubscribeDevelopersGuide.

244

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Printing an IS Document Type

YoucanusetheView as HTMLcommandtoproduceaprintableversionofanISdocument type. To print an IS document type 1 2 OpentheISdocumenttypeyouwanttoprintandclickitstitlebarintheeditorto giveitthefocus. FromtheFilemenu,selectView as HTML. DeveloperexpandsanydocumentanddocumentlistfieldsintheISdocumenttype, createsanHTMLpagecontainingtheISdocumenttype,anddisplaystheHTML pageinyourdefaultbrowser. 3 IfyouwanttoprinttheISdocumenttype,selectyourbrowsersprintcommand.

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

YoucanuseanISdocumenttypeasthesetofinputoroutputparametersforaserviceor specification.Ifyouhavemultipleserviceswithidenticalinputparametersbutdifferent outputparameters,youcanuseanISdocumenttypetodefinetheinputparameters ratherthanmanuallyspecifyingindividualinputfieldsforeachservice. To use an IS document type as service input or output parameters 1 2 3 OpentheservicetowhichyouwanttoassigntheISdocumenttype. Clickthe Input/Outputtab. IntheInputorOutputbox(dependingonwhichhalfoftheInput/Outputtabyouwantto applytheISdocumenttypeto),typethefullyqualifiednameoftheISdocumenttype orclick toselectitfromalist.YoucanalsodraganISdocumenttypefromthe NavigationpaneltotheboxbelowtheValidate inputorValidate outputcheckboxeson theInput/Outputtab. OntheFilemenu,clickSave. Important! WhenanISdocumenttypeisassignedtotheinputoroutputofa service,youcannotadd,delete,ormodifythefieldsonthathalfofthe Input/Output tab.

webMethods Developer Users Guide Version 7.1.1

245

9 Creating IS Schemas, IS Document Types, and Specifications

Using an IS Document Type to Build a Document Reference or Document Reference List Field
YoucanuseanISdocumenttypetobuildadocumentreferenceordocumentreference listfield.ByreferencinganISdocumenttypeinsteadofcreatinganewone,youcan reducethetimerequiredtocreatefieldsandmaintainbetterconsistencyforfieldnames. Youmightfindreferencingfieldsespeciallyusefulforinformationthatisrepeatedover andoveragain,suchasaddressinformation. Tip! Youcanalsouseapublishabledocumenttypetobuildadocumentreferenceor documentreferencelistfield. To use a document type to build a document reference or document reference list 1 Onthe Input/Outputtab,click Click... Document Reference Document Reference List 2 3 4 5 To... CreateadocumentfieldbasedonanISdocumenttype. CreateadocumentlistfieldbasedonanISdocument type. onthetoolbarandselectoneofthefollowing:

IntheNamefield,typethefullyqualifiednameoftheISdocumenttypeorselectit fromthelistnexttoFolder. ClickOK. Typethenameofthefield. PressENTER. Important! Ifyouarecreatingadocumentreferenceordocumentreferencelistfield basedonanISdocumenttype,youcannotdirectlyadd,delete,ormodifyits membersontheInput/Output tab.Toeditthereferenceddocumentordocument list,selectitintheNavigationpanel,lockit,andthenedititsfieldsintheeditor. Tip! YoucanalsoaddadocumentreferencebydragginganISdocumenttypefrom theNavigationpaneltotheboxbelowtheValidate inputorValidate outputcheckboxes ontheInput/Outputtab.

246

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

Specifying Field Properties

Youcanspecifyadditionalpropertiesforthefield.Thesepropertiesarelocatedinthe Propertiespanel. Field properties

OnthePropertiespanel,theGeneralcategorycontainsthepropertiesofthefieldandthe Constraintscategorycontainsvalidationconstraintsforthefield.(Formoreinformation aboutspecifyingvalidationconstraints,seeApplyingConstraintstoVariableson page 255.) Note: UsetheXML Namespacepropertytoassignanamespacenametoafield.The namespacenameindicatesthenamespacetowhichthefieldbelongs.When generatingXMLSchemadefinitionsandWSDLdocuments,theIntegrationServer usesthevalueoftheXML Namespacefieldalongwiththefieldname(thelocalname)to createaqualifiedname(QName)forthefield.Formoreinformationaboutsettingthe XMLNamespaceproperty,seetheWebServicesDevelopersGuide. TheText Field,Password,Large Editor,andPick List optionsoftheString display typeproperty affecthowyouinputdataforthefieldasfollows.Theseoptionsarenotavailablefor ObjectsandObjectlists. If you want the input Enteredinatextfield Enteredasapassword,withasterisksreflectedinsteadofcharacters Select... Text Field (default) Password

Enteredinalargetextareainsteadofatextfield.Thisisusefulifyou Large Editor expectalargeamountoftextasinputforthefield,oryouneedto haveTABornewlinecharactersintheinput Tobelimitedtoapredefinedlistofvalues UsethePick list choicespropertysEditbuttontodefinethevaluesthat willappearaschoiceswhenDeveloperpromptsforinputatruntime. Pick List

webMethods Developer Users Guide Version 7.1.1

247

9 Creating IS Schemas, IS Document Types, and Specifications

Creating a Specification
AspecificationisafreestandingISelementthatdefinesasetofserviceinputsand outputs.Ifyouhavemultipleserviceswiththesameinputandoutputrequirements,you canpointeachservicetoasinglespecificationratherthanmanuallyspecifyindividual inputandoutputfieldsineachservice. Usingspecificationsprovidesthefollowingbenefits: Itreducestheeffortrequiredtobuildeachflow. Itimprovesaccuracy,becausethereislessopportunitytointroduceatypingerror whendefiningafieldname. Itmakesfuturespecificationchangeseasiertoimplement,becauseyoucanmakethe changeinoneplace(thespecification)ratherthanineachindividualservice. Ifyouuseaspecification,keepinmindthat: Anychangethatyoumaketothespecificationisautomaticallypropagatedtoall servicesthatreferencethatspecification.(Thishappensthemomentyousavethe updatedspecificationtotheserver.) Aspecificationwhollydefinestheinputandoutputparametersforaservicethat referencesit.Thismeansthatyoucannotdirectlyaltertheservicesinputandoutput parametersthroughitsInput/Outputtab.(Developerdisplaystheparameters,butdoes notallowyoutochangethem.)Tomakechangestotheinputandoutputparameters oftheservice,youmustmodifythespecification(whichaffectsallservicesthat referenceit)ordetachthespecificationsoyoucanmanuallydefinetheparameterson theservicesInput/Outputtab. YoucreateaspecificationwithDeveloper.Youassignaspecificationtoaserviceusingthe Input/Outputtabfortheservice.

248

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

To create a specification 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectSpecification,andclickNext. IntheNewServiceSpecificationdialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefoldertowhichyouwanttosavethe specification. IntheNamefield,typeanameforthespecificationusinganycombinationof letters,numbers,andtheunderscorecharacter. Important! Developerdoesnotallowtheuseofcertainreservedwords(suchasfor, while,andif )asnames.Ifyouspecifyanamethatisareservedword,youwill receiveanerrormessage.Whenthishappens,useadifferentnameortryaddinga letterornumbertothenameyouspecifiedtomakeitvalid. c 4 ClickFinish.

Ifyouwantthisspecificationtoreferenceanotherspecification,dothefollowingin theeditor: a b InSpecification Referencefield,typethespecificationsnameorclick fromalist. Skiptherestofthisprocedure. Important! Typically,youdonotbuildaspecificationbyreferencinganother specification.However,itisusefultodothisinthesituationwhereyouwilluse thespecificationwithagroupofserviceswhoserequirementsareexpectedto change(thatis,theymatchanexistingspecificationnowbutareexpectedto changeatsomepointinthefuture).Referencingaspecificationgivesyouthe convenienceofusinganexistingspecificationandtheflexibilitytochangethe specificationforonlythatsinglegroupofservicesinthefuture. toselectit

webMethods Developer Users Guide Version 7.1.1

249

9 Creating IS Schemas, IS Document Types, and Specifications

IfyouwanttoreferenceanISdocumenttypefortheInputorOutputhalfofthe specification,dothefollowing: a IntheInputorOutputfield(dependingonwhichhalfofthespecificationyouwant toassigntheISdocumenttypeto),typetheISdocumenttypenameorclick to selectitfromalist.YoucanalsodraganISdocumenttypefromtheNavigation paneltotheboxbelowtheValidate inputorValidate outputcheckboxesonthe Input/Outputtab.ForinformationaboutcreatingISdocumenttypes,seeCreating anISDocumentTypeonpage 233. Tip! YoucanselectapublishabledocumenttypeoranISdocumenttypeto definetheinputoroutputhalfofthespecification. b Proceedtothenextsteptospecifythefieldsfortheotherhalfofthespecification. (IfyouassignedISdocumenttypestoboththeInputandOutputsidesofthis specification,skiptherestofthisprocedure.) Important! OnceyouassignanISdocumenttypetotheInputorOutputsideofa specification,youcannotadd,delete,ormodifythefieldsonthathalfofthe Input/Outputtab.

Foreachinputoroutputfieldthatyouwanttodefine,dothefollowing: a b c d Selectthehalfofthespecification(InputorOutput)whereyouwanttodefinethe fieldbyclickinganywhereinthathalfslargewhitetextbox. Click onthetoolbarandselectthetypeoffieldthatyouwanttospecify.

TypethenameofthefieldandthenpressENTER. Withthefieldselected,setitspropertiesandapplyconstraintsontheProperties panel(optional). Fordetailsonsettingfieldproperties,seeSpecifyingFieldPropertieson page 247.Fordetailsonapplyingconstraints,seeApplyingConstraintsto Variablesonpage 255.

Ifthefieldisadocumentoradocumentlist,repeatstepsbdtodefineeachofits members.Use field. toindenteachmemberbeneaththedocumentordocumentlist

OntheFilemenu,clickSave.

250

webMethods Developer Users Guide Version 7.1.1

9 Creating IS Schemas, IS Document Types, and Specifications

To assign a specification to a service 1 2 3 Opentheservicetowhichyouwanttoassignaspecification. ClicktheInput/Outputtab. InSpecification Reference,typethefullyqualifiednameofthespecification,orclick toselectitfromalist. Important! Whenaspecificationisassignedtoaservice,youcannotadd,delete,or modifythedeclaredfieldsusingthatservicesInput/Outputtab.

webMethods Developer Users Guide Version 7.1.1

251

9 Creating IS Schemas, IS Document Types, and Specifications

252

webMethods Developer Users Guide Version 7.1.1

10

Performing Data Validation

254 255 259 263 263 264 265 266

What Is Data Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Constraints to Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Input/Output Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Document Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Pipeline Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing XML Validation in webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Validation from within a Java Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

253

10 Performing Data Validation

What Is Data Validation?

Datavalidationistheprocessofverifyingthatruntimedataconformstoapredefined structureandformat.Datavalidationalsoverifiesthatruntimedataisaspecificdata typeandfallswithinadefinedrangeofvalues. Byperformingdatavalidation,youcanmakesurethat: Thepipeline,adocument(IDataobject),oranXMLdocumentcontainsthedata neededtoexecutesubsequentservices.Forexample,ifaserviceprocessesapurchase order,youmightwanttoverifythatthepurchaseordercontainsacustomername andaddress. Thedataisinthestructureexpectedbysubsequentservices.Forexample,aservice thatprocessesapurchaseordermightexpectthecustomeraddresstobeadocument fieldwiththefollowingfields:name,address,city,state,andzip. Dataisofthetypeandwithinavaluerangeexpectedbyaservice.Forexample,ifa serviceprocessesapurchaseorder,youmightwanttomakesurethatthepurchase orderdoesnotcontainanegativequantityofanitem(suchas5shirts). ByusingthedatavalidationcapabilitiesbuiltintowebMethodsIntegrationServer,you candecidewhetherornottoexecuteaservicebasedonthevalidityofdata.The validationcapabilitiescanalsoeliminateextravalidationcodefromyourservices.

What Is Data Validated Against?

Duringvalidation,runtimedataiscomparedtoablueprintormodel.Theblueprintor modelisaformaldescriptionofthestructureandtheallowablecontentforthedata.The blueprintidentifiesstructuralandcontentconstraintsforthedatabeingvalidated.The validationengineinwebMethodsIntegrationServerconsidersthedatatobevalidwhen itconformstotheconstraintsspecifiedintheblueprint.AblueprintcanbeanISschema, anISdocumenttype,orasetofinputandoutputparameters. Theblueprintusedtovalidatedatadependsonthetypeofvalidationyouare performing.InwebMethodsIntegrationServer,youcanperformthefollowingtypesof validation: Input/Output validation. ThevalidationengineinwebMethodsIntegrationServer validatestheinputand/oroutputofaserviceagainstthesignatureoftheservice. Document validation.ThevalidationengineinwebMethodsIntegrationServervalidates thestructureandcontentofadocument(IDataobject)inthepipelineagainstanIS documenttype. Pipeline validation. ThevalidationengineinwebMethodsIntegrationServervalidates thestructureandcontentofthepipelineagainstanISdocumenttype.

254

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

XML validation.ThevalidationengineinwebMethodsIntegrationServervalidatesthe structureandcontentofanXMLdocumentagainstanISschema. Thefollowingsectionsprovideinformationaboutperformingeachtypeofvalidationand informationaboutapplyingconstraintstofields.

Applying Constraints to Variables

Inpipeline,document,andinput/outputvalidation,theblueprintusedfordata validationrequiresconstraintstobeappliedtoitsvariables.Constraintsarethe restrictionsonthestructureorcontentofvariables.Youcanapplythefollowingtypesof constraintstovariables: Structural constraintsspecifytheexistenceandstructureofvariablesatruntime.For example,iftheflowserviceinwhichyouarevalidatingthepipelineprocessesa purchaseorder,youmightwanttocheckthatvaluesforthepurchaseOrderNumber, accountNumber,andcustomerNamevariablesexistatruntime. Fordocumentanddocumentlistvariables,youcanalsospecifythestructureofthe variable;thatis,youcanspecifywhatvariablescanbecontainedinthedocument (IDataobject)ordocumentlist(IData[]object)atruntime.Forexample,youcould specifythatthelineItemdocumentvariablemustcontainthechildvariables itemNumber,quantity,size,color,andunitPrice.YoucouldalsospecifythatthelineItem documentcanoptionallycontainthechildvariablespecialInstructions. Contentconstraintsdescribethedatatypeforavariableandthepossiblevaluesforthe variableatruntime.YoucanapplycontentconstraintstoString,Stringlist,String table,Object,andObjectlistvariables. WhenyouspecifyacontentconstraintforaString,StringlistorStringtablevariable, youcanalsoapplyaconstrainingfacettothecontent.Aconstrainingfacetplaces limitationsonthecontent(datatype).Forexample,foraStringvariablenamed itemQuantity,youmightapplyacontentconstraintthatrequiresthevaluetobean integer.Youcouldthenapplyconstrainingfacetsthatlimitthecontentof itemQuantitytoavaluebetween1and100. YoucanusesimpletypesfromanISschemaascontentconstraintsforString,String list,orStringtablevariables. Forpipelineanddocumentvalidation,theISdocumenttypeusedastheblueprintneeds tohaveconstraintsappliedtoitsvariables.Forinput/outputvalidation,constraintsneed tobeappliedtothedeclaredinputandoutputparametersoftheservicebeingvalidated. Note: WhenyoucreateanISdocumenttypefromanXMLSchemaoraDTD,the constraintsappliedtotheelementsandattributesintheoriginaldocumentare preservedinthenewISdocumenttype.FormoreinformationaboutcreatingIS documenttypes,seeCreatinganISDocumentTypeonpage 233.

webMethods Developer Users Guide Version 7.1.1

255

10 Performing Data Validation

To apply constraints to a variable 1 Selectthevariabletowhichyouwanttoapplyconstraints. YoucanapplyconstraintstovariablesinISdocumenttypes,variablesina specification,andvariablesdeclaredontheInput/Outputtab. 2 IntheConstraintscategoryonthePropertiespanel,dothefollowing: a Ifyouwanttorequiretheselectedvariabletoexistatruntime,settheRequired propertytoTrue.Iftheexistenceofthevariableisoptional,setthispropertyto False. Ifyouwanttoallowavariabletohaveanullvalue,settheAllow null propertyto True.Ifyouwantthevalidationenginetogenerateanerrorwhenthevariablehas anullvalue,settheAllow null propertytoFalse. Iftheselectedvariableisadocumentordocumentlistandyouwanttoallowitto containundeclaredchildvariables,settheAllow unspecified fieldspropertytoTrue. IfthispropertyissettoFalse,anychildvariablesthatexistinthepipelinebutdo notappearinthedeclareddocumentfieldwillbetreatedaserrorsatruntime. Note: ThestateoftheAllow unspecified fieldspropertydetermineswhetherthe documentisopenorclosed.Anopendocumentpermitsundeclaredfields (variables)toexistatruntime.Acloseddocumentdoesnotallowundeclared fieldstoexistatruntime.TheIntegrationServerconsidersadocumenttobe openiftheAllow unspecified fieldspropertyissettoTrueandconsidersa documenttobeclosediftheAllow unspecified fieldspropertyissettoFalse. d IftheselectedvariableisaString,Stringlist,orStringtable,andyouwantto specifycontentconstraintsforthevariable,click andthendooneofthe following:

Ifyouwanttouseacontenttypethatcorrespondstoabuiltinsimpletypein XMLSchema,intheContent typelist,selectthetypeforthevariablecontents. (Foradescriptionofthesecontentconstraints,seeAppendix F,Validation ContentConstraints.)Toapplytheselectedtypetothevariable,clickOK. Ifyouwanttocustomizethecontenttypebychangingtheconstrainingfacets appliedtothetype,seeCustomizingaStringContentTypeonpage 257.

IfyouwanttouseasimpletypefromanISschemaasthecontentconstraint, clicktheBrowsebutton.IntheBrowsedialogbox,selecttheISschema containingthesimpletypeyouwanttoapply.Then,selectthesimpletypeyou wanttoapplytothevariable.Toapplytheselectedtypetothevariable,click OK. Ifyouwanttocustomizethecontenttypebychangingtheconstrainingfacets appliedtothetype,seeCustomizingaStringContentTypeonpage 257.

256

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

Note: AcontenttypecorrespondstoasimpletypefromanXMLSchema definition.AllofthechoicesintheContent typelistcorrespondtosimpletypes definedinXMLSchemaPart2:Datatypes. e IftheselectedvariableisanObjectorObjectlist,fortheJava wrapper typeproperty, selecttheJavaclassforthevariablecontents.IfyoudonotwanttoapplyaJava classoriftheJavaclassisnotlisted,selectUNKNOWN. FormoreinformationaboutsupportedJavaclassesforObjectsandObjectlists, seeJavaClassesforObjectsonpage 407. 3 4 Repeatthisprocedureforeachvariabletowhichyouwanttoapplyconstraintsinthe ISdocumenttype,specification,serviceinput,orserviceoutput. OntheFilemenu,clickSave.

Considerations for Object Constraints

ConstraintsforObjectandObjectlistvariablescorrespondtoJavaclasses,whereas constraintsforStringvariablescorrespondtosimpletypesinXMLschemas.Whenyou applyconstraintstoObjectsandperformvalidation,thedataisvalidatedasbeingofthe specifiedJavaclass.FordetailsontheJavaclassesyoucanapplytoanObjectorObject list,seeJavaClassesforObjectsonpage 407. AconstrainedObjectisvalidatedwhenoneofthefollowingoccur: AservicerunswiththeValidate inputorValidate outputcheckboxselectedonthe Input/Outputtab. AservicerunsviatheINVOKEstepinaflowservicewiththeValidate inputorValidate outputpropertiessetontheINVOKEstep. Thepub.schema:validateserviceruns. Adocumentispublished.Whenthisoccurs,thecontentsofthedocumentare validatedagainstthespecifieddocumenttype.Fordetails,seethePublishSubscribe DevelopersGuide. Duringtesting,whenyouentervaluesforaconstrainedObjectorObjectlistinthe Inputdialogbox. WhenyouassignavaluetoanObjectorObjectlistvariableonthePipelinetabusing theSet Value modifier.

Customizing a String Content Type

InsteadofapplyinganexistingcontenttypeorsimpletypetoaString,Stringlist,or Stringtablevariable,youcancustomizeanexistingtypeandapplythenew,modified typetoavariable.Youcustomizeacontenttypeorsimpletypebychangingthe constrainingfacetsappliedtothetype.

webMethods Developer Users Guide Version 7.1.1

257

10 Performing Data Validation

Whenyoucustomizeatype,youactuallycreateanewcontenttype.Developersavesthe changesasanewcontenttypenamedcontentType_customized.Forexample,ifyou customizethestringcontenttype,Developersavesthenewcontenttypeas string_customized. Note: WhenyoueditasimpletypedefinitioninanISschema,thechangesaresavedto theselectedtypedefinitionintheISschema.Themodificationsaffectanyvariableto whichthesimpletypeisappliedasacontenttypeconstraint.Formoreinformation abouteditingasimpletypedefinition,seeEditingaSimpleTypeinanISSchema onpage 231. Whencustomizingacontenttype,keepthefollowingpointsinmind: Whenyouedittheconstrainingfacetsappliedtoacontenttype,youcanonlymake theconstrainingfacetvaluesmorerestrictive.Theconstrainingfacetscannotbecome lessrestrictive.Formoreinformationaboutsettingvaluesforconstrainingfacets,see SettingConstrainingFacetValuesonpage 233. Theconstrainingfacetsyoucanspecifydependonthecontenttype.Formore informationabouttheconstrainingfacetsforeachcontenttype,seeAppendix C, SupportedDataTypesonpage 405. Thecustomizedcontenttypeappliesonlytotheselectedvariable.Tomakechanges thataffectallvariablestowhichthecontenttypeisapplied,editthecontenttypein theISschema.(StringcontenttypesaresimpletypesfromISschemas.)Formore informationabouteditingsimpletypes,seeEditingaSimpleTypeinanISSchema onpage 231. To customize a content type 1 2 Selectthevariabletowhichyouwanttoapplyacustomizedcontenttype. IntheConstraintscategoryonthePropertiespanel,clicktheContent typebrowse button( )andthendooneofthefollowingtoselectthecontenttypeyouwantto customize:

IntheContent typelist,selectthecontenttypeyouwanttocustomize. IfyouwanttocustomizeasimpletypefromanISschema,clicktheBrowsebutton. IntheBrowsedialogbox,selecttheISschemacontainingthesimpletype.Then, selectthesimpletypeyouwanttocustomizeandapplytothevariable.

ClicktheCustomizebutton.Developermakestheconstrainingfacetfieldsbelowthe Content typelistavailablefordataentry(thatis,changesthebackgroundofthe constrainingfacetfieldsfromgreytowhite).Developerchangesthenameofthe contenttypetocontentType_customized. InthefieldsbelowtheContent typelist,specifytheconstrainingfacetvaluesyouwant toapplytothecontenttype.Formoreinformationaboutconstrainingfacets,see ConstrainingFacetsonpage 448.

258

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

ClickOK.Developersavesthechangesasanewcontenttypenamed contentType_customized. Note: TheconstrainingfacetsdisplayedbelowtheContent typelistdependonthe primitivetypefromwhichthesimpletypeisderived.Primitivetypesarethebasic datatypesfromwhichallotherdatatypesarederived.Forexample,ifthe primitivetypeisstring,Developerdisplaystheconstrainingfacetsenumeration, length,minLength,maxLength,andpattern.Formoreinformationaboutprimitive types,refertoXMLSchemaPart2:Datatypesat http://www.w3.org/TR/xmlschema2/. Important! Developerthrowsexceptionsatdesigntimeiftheconstrainingfacetvalues foracontenttypearenotvalid.Formoreinformationabouttheseexceptions,see Appendix G,ValidationErrorsandExceptions

Viewing the Constraints Applied to Variables

Developerdisplayssmallsymbolsnexttoavariableicontoindicatetheconstraints appliedtothevariable.Developerdisplaysvariablesinthefollowingways: Variable Constraint status Requiredfield. Optionalfield. Requiredfieldwithcontenttypeconstraint Optionalfieldwithcontenttypeconstraint

Note: DeveloperdisplaysthesymbolnexttoString,Stringlist,andStringtable variableswithacontenttypeconstraintonly.Developerdoesnotdisplaythe symbolnexttoObjectandObjectlistvariableswithaspecifiedJavaclassconstraint. ObjectandObjectlistswithanappliedJavaclassconstrainthaveauniqueicon.For moreinformationabouticonsforconstrainedObjects,seeJavaClassesforObjects onpage 407.

Performing Input/Output Validation

Ininput/outputvalidation,thevalidationengineinwebMethodsIntegrationServer validatestheinputsand/oroutputsofaserviceagainstthedeclaredinputandoutput parametersoftheservice.Ifyouspecifythatyouwanttovalidatetheinputstothe service,thevalidationenginevalidatestheserviceinputvaluesimmediatelybeforethe

webMethods Developer Users Guide Version 7.1.1

259

10 Performing Data Validation

serviceexecutes.Ifyouspecifythatyouwanttovalidatetheoutputsoftheservice,the validationenginevalidatestheserviceoutputvaluesimmediatelyaftertheservice executes.Aninputoroutputvalueisinvalidifitdoesnotconformtotheconstraints appliedtotheinputoroutputparameter. Forinput/outputvalidation,theservicessdeclaredinputandoutputparametersactas theblueprintormodelagainstwhichinput/outputvaluesarevalidated.Toeffectively usetheinputandoutputparametersastheblueprintforvalidation,youneedtoapply constraintstotheparameters.Forinformationaboutapplyingconstraintstovariables, seeApplyingConstraintstoVariablesonpage 255.Forinformationaboutdeclaring serviceinputandoutputparameters,seeDeclaringInputandOutputParametersfora Serviceonpage 122.
.

Note: Thedeclaredinputandoutputparametersforaservicearesometimescalledthe signatureoftheservice. Youcanspecifythatyouwanttoperforminput/outputvalidationforaserviceinthe followingways: Input/Output tab.SetpropertiesontheInput/Outputtabtoinstructthevalidationengine inwebMethodsIntegrationServertovalidatetheinputsand/oroutputsoftheservice everytimetheserviceexecutes.Ifaclientcallstheserviceandtheinputsareinvalid, theservicefailsanddoesnotexecute. INVOKE step properties.Setupinput/outputvalidationviatheINVOKEstepproperties toinstructthevalidationenginetovalidatetheserviceinputand/oroutputonly whenitiscalledfromwithinanotherflowservice.Atruntime,iftheinputsand/or outputsoftheserviceareinvalid,theINVOKEflowstepthatcallstheservicefails. Todeterminewhichmethodtouse,determinewhetherornotyouwanttheserviceinput andoutputvaluesvalidatedeverytimetheserviceruns.Ifyouwanttovalidatetheinput andoutputvalueseverytimetheserviceruns,specifyvalidationviatheInput/Outputtab. Forexample,ifyourservicerequirescertaininputtoexistorfallwithinaspecifiedrange ofvalues,youmightwantthepipelinevalidatedeverytimetheserviceruns. Iftheinputand/oroutputvaluesdonotneedtobevalidatedeverytimetheservice executes,setupvalidationviatheINVOKEstepproperties.Specifyinginput/output validationviatheINVOKEsteppropertiesallowsyoutodecideonacasebycasebasis whetheryouwantvalidationperformed. Note: Ifyouspecifyinput/outputvalidationviatheINVOKEstepandaninputor outputvalueisinvalid,theserviceitselfdoesnotactuallyfail.Thevalidationengine validatesinputvaluesbeforewebMethodsIntegrationServerexecutestheservice.If theserviceinputisnotvalid,theINVOKEflowstepfortheservicefails.Similarly,the validationenginevalidatesoutputvaluesafterwebMethodsIntegrationServer executestheservice.Iftheserviceoutputisnotvalid,theINVOKEflowstepforthe servicefails.Whetherornottheentireflowservicefailswhenanindividualflowstep failsdependsontheexitconditionsfortheservice.Forinformationaboutspecifying exitconditions,seeUsingSEQUENCEtoSpecifyanExitConditiononpage 176.

260

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

Specifying Input/Output Validation via the Input/Output Tab

Youcanspecifythatyouwanttheinputsand/oroutputsofaservicevalidatedeverytime itexecutesbysettingpropertiesontheInput/Outputtaboftheservice.Everytimethe serviceexecutes,thevalidationenginevalidatestheinputand/oroutputvaluesofthe serviceagainsttheinputandoutputparametersdeclaredfortheservice. To set up input and output validation via the Input/Output tab 1 2 3 4 5 Opentheserviceforwhichyouwanttovalidateinputand/oroutputeverytimethe serviceisinvoked. ClicktheInput/Outputtab. Ifyouwanttheinputoftheservicevalidatedeverytimetheserviceexecutes,select theValidate inputcheckbox. Ifyouwanttheoutputoftheservicevalidatedeverytimetheserviceexecutes,select theValidate outputcheckbox. OntheFilemenu,clickSave. Input/Output tab with validation processing enabled

Service input values will be validated every time the service executes.

Service output values will not be validated.

webMethods Developer Users Guide Version 7.1.1

261

10 Performing Data Validation

Specifying Input/Output Validation via the INVOKE Step

Youcanalsospecifyinput/outputvalidationbysettingpropertiesfortheINVOKEstep thatcallstheservice.Eachtimeyouinsertaserviceintoaflow,youcandecidewhether youwantthevalidationenginetovalidateserviceinputsand/oroutputsatruntime. To set up input and output validation via the INVOKE step 1 2 Inthefloweditor,selecttheINVOKEstepcontainingtheserviceforwhichyouwant IntegrationServertovalidateinputand/oroutputvalues. IntheGeneralcategoryonthePropertiespanel,dothefollowing:

Ifyouwanttovalidateinputtotheservice,settheValidate input propertytoTrue. Ifyouwanttovalidatetheoutputoftheservice,settheValidate output propertyto True.

OntheFilemenu,clickSave. INVOKE properties with validation processing enabled

Inputs to the invoked service will be validated. Outputs of the service will not be validated.

Important! KeepinmindthattheValidate inputandValidate outputpropertiesare independentofanyvalidationsettingsthatyoumighthavealreadysetintheservice. IfyouselecttheValidate input and/orValidate outputcheckboxesontheInput/Outputtab oftheinvokedservice,theneverytimetheserviceexecutes,input/outputvalidation isperformed.Ifyoualsospecifyinput/outputvalidationviatheINVOKEstep, duplicatevalidationwillresult,possiblyslowingdowntheexecutionoftheservice.

262

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

Performing Document Validation

Sometimes,youmightwanttovalidateanindividualdocument(IDataobject)inthe pipelineinsteadoftheentirepipeline.Usingthepub.schema:validateservice,youcan validateasingledocument(IDataobject)inthepipelineagainstanISdocumenttype. Forexample,supposethatyouinvokethepub.client.ldap:searchserviceinaflowtoretrieve anIDataobjectfromanLDAPdirectoryservice.Ifyouwanttovalidatethatobjectbefore youuseitinotherservices,invokethepub.schema:validateserviceafterretrievingtheobject. Asanotherexample,youmightwanttovalidateanXMLdocumentthathasbeen convertedtodocument(IDataobject).Youwouldusethepub.schema:validateserviceto validatetheresultingdocument(IDataobject)againstanISdocumenttype. Thepub.schema:validateserviceconsidersadocument(IDataobject)tobevalidwhenit complieswiththestructuralandcontentconstraintsdescribedintheISdocumenttypeit isvalidatedagainst.Thisservicereturnsastringthatindicateswhethervalidationwas successfulandanIDataarraythatcontainsanyvalidationerrors.Whenyouinsertthe pub.schema:validateserviceintoaflowservice,youcanspecifythemaximumnumberof errorstobecollectedbytheservice.Youcanalsospecifywhetherthepub.schema:validate serviceshouldfailifthedocument(IDataobject)isinvalid. Formoreinformationaboutthepub.schema:validateservice,seethewebMethodsIntegration ServerBuiltInServicesReference. Note: ThevalidationengineinIntegrationServerperformsdocument(IDataobject) validationautomaticallywhenadocumentispublished.Thevalidationengine validatesthepublisheddocumentagainstthepublishabledocumenttype. Tip! IfyouwanttovalidateonlyString,Stringlist,orStringtablevariablesinthe pipeline,usethepub.schema:validatePipelineservice. DefineanISdocumenttypethat containsthevariablesyouwanttovalidateandapplyconstraintstothevariables. ThenusethisISdocumenttypeastheblueprintforthepub.schema:validatePipeline service.OnlythevariablesintheISdocumenttypewillbevalidated.Thevalidation engineignoresothervariablesthatexistinthepipelineatruntime.(AnISdocument typeimplicitlyallowsunspecifiedvariablestoexistatruntime.)

Performing Pipeline Validation

PipelinevalidationistheprocessofverifyingthecontentsofthepipelineagainstanIS documenttype.Byvalidatingpipelinedata,youcan: Ensureahigherdegreeofaccuracyforpipelinecontent. Executeornotexecuteaservicebasedonthevalidityofthepipelinedata. Eliminateextravalidationcodeinyourservice. Inpipelinevalidation,anISdocumenttypeistheblueprintormodelagainstwhichyou validatethepipeline.TheconstraintsappliedtothevariablesintheISdocumenttype

webMethods Developer Users Guide Version 7.1.1

263

10 Performing Data Validation

determinewhatcanandcannotbeincludedinthepipeline.Formoreinformationabout applyingconstraintstovariables,seeApplyingConstraintstoVariablesonpage 255. Tovalidatethepipeline,invokethebuiltinservice pub.schema:validatePipeline.Thisservice instructsthevalidationenginetocomparethepipelinecontentsagainstaspecifiedIS documenttype.Thepipelineisvalidwhenitconformstothestructuralandcontent constraintsappliedtotheISdocumenttype.Thepub.schema:validatePipelineservicereturns astringthatindicateswhethervalidationwassuccessfulandanIDataarray(errors variable)thatcontainsanyvalidationerrors.Formoreinformationaboutthe pub.schema:validatePipelineservice,seethewebMethodsIntegrationServerBuiltInServices Reference.

Performing XML Validation in webMethods Integration Server

InwebMethodsIntegrationServer,XMLvalidationistheprocessofverifyingthe structureandcontentofanXMLdocumentagainstanISschema.ByvalidatinganXML document,youcanensurethattheXMLdocumentcontainstheelementsandattributes organizedinthestructureorformatexpectedbysubsequentservices.Youcanalso ensurethattheelementsandattributescontainvaluesthatareofthedatatypeexpected bysubsequentservices.InwebMethodsIntegrationServer,anXMLdocumentisvalid whenitcomplieswiththestructuralandcontentconstraintsdescribedintheISschemait isvalidatedagainst. Forexample,ifyoureceiveanXMLdocumentthatcontainsnewemployeeinformation, youmightwanttovalidatetheemployeeinformationbeforeexecutingsubsequent services.YoumightwanttomakecertaintheXMLdocumentcontainsanemployee name,anaddress,telephonenumber,anddateofbirthinformation.Additionally,you mightwanttovalidatethedateofbirthinformationtomakesurethatitconformstoa specificdateformat. TovalidateanXMLdocument,invokethepub.schema:validateservice.Thisserviceinstructs thevalidationenginetovalidateanXMLdocumentbycomparingittoaspecifiedIS schemaoranISdocumenttypeintheNavigationpanel.TheXMLdocumentisvalidifit complieswiththestructuralandcontentconstraintsdescribedintheISschemaorIS documenttype.Thepub.schema:validateservicereturnsastringthatindicateswhether validationwassuccessfulandanerrorsvariable(anIDataarray)thatcontainsany validationerrors.Forinformationabouterrorsthatcanoccurduringvalidation,see ValidationErrorsandExceptionsonpage 266. Important! Thepub.schema:validateservicerequiresaparsedXMLdocumentasinput(an XMLnode).TheIntegrationServerparsesXMLdocumentsitreceivesviaHTTPor FTPautomatically.Youcanalsousethepub.xml:loadXMLNodeserviceorthe pub.xml:xmlStringToXMLNodetoparseanXMLdocument.Formoreinformationabout submittingXMLdocumentstoservices,seetheXMLServicesDevelopersGuide.For moreinformationaboutthepub.xmlservices,seethewebMethodsIntegrationServer BuiltInServicesReference.

264

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

Note: IfanISschemacontainsanelementwithanillableattributeandtheelement generatedfromtheschemaalsocontainstheattributexsi:nil=true,nodocument validationisperformedonthegeneratedelement.

Performing Validation from within a Java Service

Youcanusebuiltinservicespub.schema:validateandpub.schema:validatePipelinetoperform validationfromwithinaJavaservice.Inthefollowingexample,thepub.schema:validate serviceisusedtovalidatetheresultsofthepub.xml:xmlNodeToDocument serviceagainsta specificationforanOAGpurchaseorder.
. . . IData validInput; IData dtrResult; . . . // initialize the folder and document type name to point to a document type // that exists on webMethods Integration Server String ifc = "OAG.PO" String rec = "purchaseOrder" // put the result from the xmlNodeToDocument service (i.e, the object to be // validated) into the key named <object> IDataCursor validCursor = validInput.getCursor(); IDataCursor dtrCursor = drtResult.getCursor(); if (dtrCursor.first("boundNode")) { // assumption here that there's data at the current cursor position validCursor.insertAfter( "object", dtrCursor.getValue() ); } dtrCursor.destroy(); // set <conformsTo> parameter to point to the document type to validate against // This document type must exist on webMethods Integration Server validCursor.insertAfter( "conformsTo", ifc+":"+rec ); // set the <maxErrors> parameter to the number of allowed validation errors validCursor.insertAfter( "maxErrors", "1000" ); validCursor.destroy(); // invoke pub.schema.validate to validate contents of <object> IData validResult = context.invoke("pub.schema", "validate", validInput);

webMethods Developer Users Guide Version 7.1.1

265

10 Performing Data Validation

// check <isValid> to see whether <object> is valid and process accordingly IDataCursor validCursor = validResult.getCursor(); if(validCursor.first("isValid")) { if (IDataUtil.getString(validCursor).equals("false")) { IData [] vr = IDataUtil.getIDataArray(validCursor, "errors"); System.out.println ( vr.length+" ERROR(s) found with example"); for (int j=0; j < vr.length; j++ ) { System.out.println( vr[j].toString() ); } } } validCursor.destroy(); . . .

Foradditionalinformationaboutpub.schema:validateandpub.schema:validatePipeline,seethe SchemaservicesinthewebMethodsIntegrationServerBuiltInServicesReference.

Validation Errors and Exceptions

Duringdatavalidation,thevalidationenginegenerateserrorswhenitencountersvalues thatdonotconformtothestructuralandcontentconstraintsspecifiedintheblueprint. Theformatinwhichthevalidationenginereturnserrorsdependsonwhethervalidation wasperformedusingthebuiltinservicesorbycheckingthedeclaredinputandoutput parametersfortheservice. Whenthevalidationengineperformsdatavalidationbyexecutingthebuiltin servicespub.schema:validateorpub.schema:validatePipeline,errorsarereturnedintheerrors outputvariable(anIDatalist).Foreachvalidationerror,theerrorsvariableliststhe errorcode,theerrormessage,andthelocationoftheerror. Whenthevalidationengineperformsvalidationbycomparingruntimedatatothe declaredinputandoutputparameters,thevalidationenginereturnsallthevalidation errorsinastring.Thisstringcontainstheerrorcode,errormessage,anderror locationforeacherrorfoundduringinput/outputvalidation. Formoreinformationaboutvalidationerrors,seeAppendix G,ValidationErrorsand Exceptions.

Validation Exceptions
Ifyouusethepub.schema:validateandpub.schema:validatePipelineservicestoperformdata validation,youcandeterminewhethertheserviceshouldsucceedorfailifthedatabeing validatedisinvalid.Youmightwantaservicetosucceedevenifthedataisinvalid.Inthe pub.schema:validateandpub.schema:validatePipelineservices,thevalueofthefailIfInvalidinput variabledetermineswhetheraservicefailsbecauseofaninvalidobject.

266

webMethods Developer Users Guide Version 7.1.1

10 Performing Data Validation

Ifthepub.schema:validateandpub.schema:validatePipelineservicefails,webMethods IntegrationServerthrowsavalidationexception.Avalidationexceptionisgeneratedif oneofthefollowingistrue: Errorsaredetectedintheobject(XMLnode,pipeline,ordocument(IDataobject)) thatispassed(forexample,nullvalue). Thebasicvalidationcontractisviolated(forexample,abinarytreeispassedinstead ofadocument(IDataobject)asexpected). Youspecifythattheserviceshouldfailiftheobjecttobevalidated(XMLnode, pipeline,ordocument(IDataobject))didnotconformtotheISschemaorIS documenttype(forexample,failIfInvalid=true).Ifthisisthereasonfortheexception, webMethodsIntegrationServerinsertsthevalidationerrorsintotheexception message.

Running Out of Memory During Validation

DuringvalidationofanXMLnode,alargemaxOccursvalueforanelementintheIS schemausedastheblueprintcancauseanoutofmemoryerrororastackoverflow.To preventastackoverfloworoutofmemoryerror,youcansetathresholdvaluefor maxOccurs.WhenthevalidationengineencountersamaxOccursvaluegreaterthanthe thresholdvalue,itproceedsasifthemaxOccursvaluewasequaltounbounded. TosetamaxOccursthresholdvalue,youcanedittheserverconfigurationparameter
watt.core.schema.maxOccursThresholdValue.Bydefault,thisparameterdoesnothavea

value. To set a maxOccurs threshold value 1 2 3 4 StartwebMethodsIntegrationServerandopentheIntegrationServerAdministrator. IntheSettingsmenuofthenavigationarea,clickExtended. ClickEdit Extended Settings.TheserverdisplaystheExtended Settingsscreen. InthetextareaunderExtended Settings,type
watt.core.schema.maxOccursThresholdValue=valuewherevalueisthenumberyou

wanttouseasthemaxOccursthreshold. 5 ClickSave Changes.

webMethods Developer Users Guide Version 7.1.1

267

10 Performing Data Validation

268

webMethods Developer Users Guide Version 7.1.1

11

Testing and Debugging Services

270 270 271 279 280 281 288 291 295 296 300

Testing and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services from Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services from a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Services that Expect XML Documents as Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working in Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Flow Steps, Transformers, and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Current Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving and Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

269

11 Testing and Debugging Services

Testing and Debugging

Likeothertypesofcomputerprogramming,developingaserviceisaniterativeprocess ofbuilding,testing,andcorrecting(debugging)yourcode. Developerprovidesarangeoftoolstoassistyouduringthetestinganddebugging phases.Forexample,youcan: Testservices,specifytheirinputvalues,andinspecttheirresults. Examinethecallstackandthepipelinewhenanerroroccurs. Executeservicesindebugmode,amodethatletsyoumonitoraflowservices executionpathand/orexecuteitsstepsoneatatime. Temporarilydisablestepsinaflowand/orspecifypointswhereyouwanttohalt execution. Additionally,IntegrationServerprovidestoolsforcollectingruntimeinformationthat canhelpdebugaservice.Theseincludetoolsto: Writearbitrarymessagestotheserverlog. Tracethepipelineatruntime. Modifyandsavethecontentsofthepipelineataspecifiedpoint. Note: ForinformationabouttestingBroker/localtriggersandpublishabledocument types,seethePublishSubscribeDevelopersGuide.

Testing Services
Youcantestanytypeofservice(flowservicesorcodedservices)withDeveloper, eliminatingtheneedtobuildspecialclientssimplyfortesting.Italsoallowsyoutoeasily passdifferentsetsoftestdatatoyourservice,whichmakesiteasytotestyourservice underavarietyofdataconditions. YoucanuseDevelopertotestservicesintwoways: From Developer. Withthistechnique,Developeristheclient.Thatis,Developerinvokes theserviceandreceivestheresults. From a browser.Withthistechnique,DeveloperformulatestheURLnecessaryto invoketheserviceandpassesthatURLtoyourbrowser.Yourbrowseractually invokestheserviceandreceivestheresults.Whenyoudevelopservicesforbrowser basedclients(especiallyoneswhoseoutputwillbeformattedusingoutput templates)youwillwanttotestthoseservicesatleastonceusingthistechnique.

270

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Testing Services from Developer

Inmostcases,youwilltestyourservicesusingDeveloper(notabrowser)astheclient. YoudothisusingtheRuncommandontheTestmenu. WhenyouexecuteaservicewiththeRuncommand,Developerinvokestheservice(just asanordinaryISclientwould)andreceivesitsresults.Theserviceexecutesonce,from beginningtoend(oruntilanerrorconditionforcesittostop)ontheserveronwhichyou haveanopensession. BeforeDeveloperinvokestheservice,itpromptsyouforinputvalues.Youcantypethe inputvaluesintothedialogboxprovidedbyDeveloperorloadthevaluesfromafilethat wassavedduringanearliertest. ResultsfromtheservicearereturnedtoDeveloperanddisplayedintheResultspanel. Thisallowsyoutoquicklyexaminethedataproducedbytheserviceandoptionally changeitorsaveittoafile.Youcanusethesaveddataasinputforalatertestorto populatethepipelineduringadebuggingsession. Note: IfyouselectedtheSwitch to Test perspectivecheckboxontheTestpageofthe Optionsdialogbox(ToolsOptions),DeveloperdisplaystheTestperspectivewhen youbegintestingaservice.Formoreinformationaboutperspectives,seeSwitching Perspectivesonpage 34. To test a service using Developer as the client 1 2 3 Opentheservicethatyouwanttotest. OntheTestmenu,selectRun.Ifyouhavenotyetsavedchangestotheservice, Developerpromptsyoutosavethem. Iftheservicehasinputparameters,typetheinputvaluesforeachvariableinthe InputdialogboxorclicktheLoadbuttontoretrievethevaluesfromafile.Formore information,seeEnteringInputforaServiceonpage 272. IfyouwantDevelopertopassemptyvariables(variablesthathavenovalue)tothe service,selecttheInclude empty values for String Types checkbox.Whenyouselectthis option,emptyStringsarepassedwithazerolengthvalue.Ifyoudonotselectthis option,emptyStringsarenotpassedtotheservice. Ifyouwanttosavetheinputvaluesthatyouhaveentered,clickSave.Inputvalues thatyousavecanberecalledandreusedinlatertests.Formoreinformationabout savinginputvalues,seeSavingInputValuestoaFileonpage 274. ClickOK.Developerinvokestheservicewiththespecifiedsetofinputvalues.

webMethods Developer Users Guide Version 7.1.1

271

11 Testing and Debugging Services

Notes: Iftheserviceexecutestocompletion,itsresultsappearontheResultspanel.Formore informationabouttheResultspanel,seeViewingtheResultsoftheServiceon page 275. Iftheservicethrowsanexception,anerrormessagedisplays.ClickDetailsinthe messageboxtoviewthecallstackandthestateofthepipelinewheretheerror occurred.Formoreinformationabouterrorsthatoccurwhiletestingaservice,see RunTimeExceptionsonpage 277.

Entering Input for a Service

WhenyoutestaservicewithDeveloper,DeveloperdisplaystheInputdialogbox,which promptsyouforinputtotheservice.Thisdialogboxcontainsanentryforeachvariable definedbytheservicesinputparameters.Objectvariableswithoutconstraintsarenoted asNoteditablebyuser. Youcanalsoenterdocumentsanddocumentlistscontainingstringbasedchildrenand constrainedobjectsthroughtheInputdialogbox. Enter input values in the Input dialog box
You can enter simple Strings...

...and complex documents and document lists.

YoucanmanuallytypeyourinputvaluesintotheInputdialogboxor,ifyousavedthe inputvaluesfromanearliertest,youcanloadthemfromafile.

272

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Note: IfyourserviceexpectsObjectvariablesthatdonothaveconstraintsassignedor anObjectdefinedasabyte[],youwillnotbeabletoenterthosevaluesintheInput dialogbox.Totestthesevaluesinaservice,youmustalsocreateaservicethat generatesinputvaluesforyourservice.Thenyouneedtoconstructatestharness(a flowservicethatexecutesboththeservicethatproducesthetestdataandtheservice youwanttotest)andusethatharnesstotestyourservice. To enter values by typing them 1 2 OpentheserviceandexecuteitasdescribedinTestingServicesfromDeveloperon page 271orTestingServicesfromaBrowseronpage 279. ForeachvariablelistedintheInputdialogbox,typeaninputvalue.Iftheservice takescomplexvariablessuchasaStringlists,documents,ordocumentlists,usethe followingbuttonstospecifythevariablesindividualelements. Use this To... Addarowtothevariable. Insertablankrowabovethecurrentlyselectedrow. Addacolumntothevariable. Deletetheselectedrowfromthevariable. Deletetheselectedcolumnfromthevariable. 3 IfyouwantDevelopertopassemptyStringstotheservice,selectthe Include empty values for String Typescheckbox.Whenyouselectthischeckbox,emptyStringsare passedwithazerolengthvalue.Ifyoudonotselectthischeckbox,emptystringsare notpassedtotheservice. Note: WhenyouentervaluesforconstrainedobjectsintheInputdialogbox, Developerautomaticallyvalidatesthevalues.Ifthevalueisnotofthetypespecified bytheobjectconstraint,Developerdisplaysamessageidentifyingthevariableand theexpectedtype.

webMethods Developer Users Guide Version 7.1.1

273

11 Testing and Debugging Services

Saving Input Values to a File

YoucansavevaluesthatyoutypeintheInputdialogboxtoafilesothatyoucanreuse theminlatertests. Whensavinginputvaluestoafile,keepthefollowingpointsinmind: Emptyvariables(variablesthatdonothaveavalue)areonlysavediftheInclude empty values for String Typescheckboxisselected.Ifyoudonotselectthischeckbox, Developerdoesnotsaveemptyvariablesinthefile. Youcanstorethefileinanydirectorythatisaccessibletothecomputeronwhich Developerisrunning.Becausethesefilesarenotactualruntimecomponents,theydo notneedtobesavedinIntegrationServersnamespaceorevenontheservermachine itself. Note: Youmightwanttoconsidercreatinganinputfileforeachsetofdatathat youroutinelytestyourserviceagainst.Thiswillprovideyouwithareadymade setoftestcasesagainstwhichtoverifytheservicewhenitismodifiedbyyouor otherdevelopersinthefuture.Manysitesestablishaspecialdirectoryontheir developmentserverjustforholdingsetsoftestdatathattheygenerateinthis manner. To save input values that you have entered for a service 1 2 3 4 OpentheserviceandexecuteitasdescribedinTestingServicesfromDeveloperon page 271orTestingServicesfromaBrowseronpage 279. EnterinputvaluesintotheInputdialogboxasdescribedinEnteringInputfora Serviceonpage 272. Whenyouarefinishedenteringvalues,clickSave. IntheSaveFiledialogbox,specifythenameofthefiletowhichyouwantthevalues saved.

Loading Input Values from a File

Youcanreloadinputvaluesthatyouhavesavedtoafileinsteadofrekeyingthevaluesin theInputdialogbox.Todothis,clicktheLoadbuttonintheInputdialogboxandthen selectthefilethatcontainstheinputvaluesyouwanttouse. Whenyouuseinputvaluesfromafile,keepthefollowingpointsinmind: Developeronlyloadsvariableswhosenameandtypematchthosedisplayedinthe Inputdialogbox.Variablesthatexistinthefile,butnotinthedialogbox,areignored. InthecaseofObjectvariableswithoutconstraintsorObjectvariablesoftypebyte[], thevaluesinthefilearenotused. ValuesfromthefilereplacethosealreadyintheInputdialogbox. VariablesthatexistintheInputdialogbox,butnotinthefile,aresettonull.

274

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

BesidesloadingvaluesthatweresavedfromtheInputdialogbox,youcanalsoload valuesthatweresavedusingpub.flow:savePipelineToFileserviceortheSave Pipeline commandsontheFilemenu.Inaddition,youcanchangevaluesinthepipeline duringtesting.Forinformationaboutsavingthestateofthepipeline,seeSavingand RestoringthePipelineonpage 296.Forinformationaboutmodifyingvaluesinthe pipeline,seeModifyingtheCurrentPipelineonpage 295. To load input values that have been saved to a file 1 2 3 OpentheserviceandexecuteitasdescribedinTestingServicesfromDeveloperon page 271. WhentheInputdialogboxappears,clickLoad.TheLoadFiledialogboxappears. Selectthefilecontainingtheinputvaluesthatyouwanttoload.

Viewing the Results of the Service

WhenyouexecuteaservicewiththeRuncommandorwithoneofDevelopersdebugging tools,itsresultsaredisplayedintheResultspanel. Results from a service you run in Developer are displayed in the Results panel

To examine the contents of a variable, select it in the top pane...

...and view it in the bottom pane.

TheupperhalfoftheResultspaneldisplaysallthevariablesinthepipeline.Toviewthe contentsofaparticularvariable,youselectthevariableintheupperhalf.Itscontentsare showninthelowerhalf.

webMethods Developer Users Guide Version 7.1.1

275

11 Testing and Debugging Services

WhenviewingtheResultspanel,keepthefollowingpointsinmind: TheResultspanelrepresentsthecontentsofthepipeline. TheResultspanelshowsallvariablesplacedinthepipelinebytheservice,notjust thosethatweredeclaredintheservicesinput/outputparameters. Variablesthataserviceexplicitlydropsfromthepipelinedonotappearonthe Resultspanel. YoucanbrowsethecontentsoftheResultspanel,butyoucannotedititdirectly. YoucansavethecontentsoftheResultspaneltoafileandusethatfiletorestorethe pipelineatalaterpoint.Foradditionalinformationaboutsavingandrestoringthe contentsoftheResultspanel,seeSavingandRestoringthePipelineonpage 296. Ifyourunaserviceandanerroroccurs,resultsarenotdisplayedintheResultspanel. However,youcanclicktheDetailsbuttonintheerrormessageboxtoexaminethe stateofthepipelineatthepointwheretheexceptionoccurred. Whendebuggingaflowserviceinstepmode,youcanusetheResultspanelto examinethestateofthepipelineaftereachflowstep.Youcanoptionallyloada differentpipelineormodifytheexistingpipelinebetweensteps.Forinformation aboutloadingapipelineintheResultspanel,seeSavingandRestoringthePipeline onpage 296.Forinformationaboutmodifyinganexistingpipeline,seeModifying theCurrentPipelineonpage 295. WhenyouuseabreakpointortheTrace to Here commandtohaltexecutionofaflow service,youcanusetheResultspaneltoexaminethepipelineatthatpointwhereyou haltedtheflow.Youmayalsooptionallyloadadifferentpipelineormodifythe existingpipelineatthispoint.ForinformationaboutloadingapipelineintheResults panel,seeSavingandRestoringthePipelineonpage 296.Forinformationabout modifyinganexistingpipeline,seeModifyingtheCurrentPipelineonpage 295. VariableswhoseobjecttypesarenotdirectlysupportedbytheDeveloperwillappear intheResultspanel,butbecauseDevelopercannotrenderthevaluesofsuchobjects, avaluedoesnotappearintheValuecolumn.Instead,theValuecolumndisplaysthe objectsJavaclassmessage. Variablesthatcontaincom.wm.util.TableobjectsappearasdocumentlistsintheResults panel.

276

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Copying Variables from the Results Panel

YoucanusetheCopycommandtocopyinformationfromtheResultspanelandpasteit intootherfieldsinDeveloper.TheinformationthatDeveloperinsertswhenyoupastean elementfromtheResultspaneldependsonthefieldintowhichyoupasteit. If you paste to a field that expects Adatadefinition(forexample,the Pipelinetab,the Input/Output tab,ora document(IDataobject)) Thenameofanelement Developer inserts Thecopiedelementsdatadefinition.

Thecopiedelementsname(andpositionifit isamemberofacomplexelementsuchasa Stringtable,document(IDataobject),or documentlist(IData[])).

To copy and paste elements from the Results panel 1 DisplaytheResultspanelandselecttheelementthatyouwanttocopy.(When copyingelementsfromthelowerhalf,youcanselectagroupofcontiguouselements bypressingtheSHIFTkeyandselectingthefirstandlastelementinthegroupthat youwanttocopy.) OntheEdit menu,clickCopy. Selectthefieldintowhichyouwanttopastetheinformation,thenclickEditPaste After.(IfthePastecommandisnotavailable,itindicatesthattheinformationcannotbe pastedintotheselectedfield.)

2 3

Run-Time Exceptions
IfaservicethatyourunfromDeveloperthrowsanexception,Developerreportstheerror inafollowingmessagebox. YoucanclicktheDetailsbuttontodisplaythecallstackandthepipelineatthepoint wheretheerroroccurred.

webMethods Developer Users Guide Version 7.1.1

277

11 Testing and Debugging Services

The Details button shows the call stack and the pipeline

...to display the call stack and the pipeline.

Note: YoucanimproveperformanceandmemoryusageinDeveloperbycaching elements,suchasservicesandschemas.Fordetails,seeCachingElementson page 66.

The Call Stack

Thecallstackidentifieswhichflowstepgeneratedtheerrorandlistsitsantecedents.For example,letssayyouhaveaservicecalledPARENTthatinvokesthreeservices,CHILD_A, CHILD_B,andCHILD_C.IfCHILD_BisaJavaserviceanditthrowsanexception,thecallstack willlooklikethis: Call stack from a nested service

This service threw the exception.

278

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

NowletsassumethatCHILD_BisaflowservicethatcallsthreeJavaservices:CHILD_B1, CHILD_B2,andCHILD_B3.IfCHILD_B3throwsanexception,thecallstackwilllooklikethis: Call stack from a deeply nested service

This service threw the exception.

NotethatthecallstackisLIFObased.Thatis,thetopentryinthestackidentifiesthelast (thatis,mostrecent)serviceinvoked.Thebottomentryidentifiestheparentservice(the onethatyouoriginallyinvokedfromDeveloper).Iftheparentitselfthrowstheexception, itwillbetheonlyentryinthecallstack. Note: ServicesinvokedfromwithinaJavaservicearenotreportedinthecallstack, eveniftheythrowtheexception.

The Pipeline Dump

TheServiceFailuresDetaildialogboxcontainsthecontentsofthepipelineatthepointof failure.NotethatwhenafailureoccurswithinaJavaservice,thePipelinearearepresents thestateofthepipelineatthepointwhenthatservicewasinitiallycalled.IftheJava servicemadechangestothesevaluesbeforethrowingtheexception,thosechangeswill notbereflectedinthePipeline information.

Testing Services from a Browser

YoucanusetheRun in BrowsercommandinDevelopertotestaservicefromabrowser (thatis,tosimulateabrowserbasedclient).Whenyouusethiscommand,Developer promptsyoufortheservicesinputvalues,buildstheURLnecessarytoinvoketheservice withtheinputsyouspecify,andthenpassestheURLtoyourbrowser.Whenyouusethis commandtotestaservice,yourbrowser(notDeveloper)actuallyinvokestheserviceand receivesitsresults.

webMethods Developer Users Guide Version 7.1.1

279

11 Testing and Debugging Services

Ifyouaredevelopingservicesthatwillbeinvokedbybrowserbasedclients,particularly oneswhoseoutputwillbeformattedusingoutputtemplates,youwillwanttotestthose servicesusingtheRun in Browsercommandtoverifythattheyworkasexpected. To test a service using a browser as the client 1 2 3 Opentheservicethatyouwanttotest. OntheTestmenu,clickRun in Browser.Ifyouhaveunsavededits,Developerprompts youtosavethem. Iftheservicehasinputparameters,typetheinputvaluesforeachvariableinthe InputdialogboxorclicktheLoadbuttontoretrievethevaluesfromafile.Formore information,seeEnteringInputforaServiceonpage 272. Note: OnlyStringsandStringlistsarepassedtothebrowser. 4 Ifyouwanttopassemptyvariables(variablesthathavenovalue)totheservice,select theInclude empty values for String Typescheckbox.Whenyouselectthisoption,empty Stringsarepassedwithazerolengthvalue.Ifyoudonotselectthisoption, Developerexcludesemptyvariablesfromthequerystringthatitpassestothe browser. Ifyouwanttosavetheinputvaluesthatyouhaveentered,clickSave.Inputvalues thatyousavecanberecalledandreusedinlatertests.Formoreinformationabout savinginputvalues,seeSavingInputValuestoaFileonpage 274. ClickOK.DeveloperbuildstheURLtoinvoketheservicewiththeinputsyouhave specified,launchesyourbrowser,andpassesittheURL.

Iftheserviceexecutessuccessfully,itsresultsappearinyourbrowser.(Ifan outputtemplateisassignedtotheservice,thetemplatewillbeappliedtothe resultsbeforetheyarereturned.) Iftheserviceexperiencesanerror,anerrormessageisdisplayedinthebrowser.

Testing Services that Expect XML Documents as Input

IfyourserviceexpectsanXMLdocumentasinput(thatis,ittakesanodeasinput),you cantestitusingtheSend XML Filecommand.Thiscommandpromptsyouforthenameof theXMLfileandsubmitsthefiletotheservice,emulatingthewayinwhichtheservice wouldexecuteifanXMLdocumentwerepostedtoit. TotestaservicebysendinganXMLfiletotheservice,youmusthaveReadaccesstothe service.

280

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

To test a service that expects an XML document as input 1 2 3 4 Opentheservicethatyouwanttotest. FromtheTestmenu,selectSend XML File.Ifyouhaveunsavededits,Developer promptsyoutosavethem. IntheSelectTestModedialogbox,specifywhetheryouwanttheservicetorunin TracemodeorStepmodeandclickOK. IntheSelectFiledialogbox,selecttheXMLfilethatyouwanttosubmittothisservice andclickOK.Developersubmitsthefiletotheserver,whichparsesitintoanode objectandpassesittoselectedservice.

Iftheserviceexecutestocompletion,itsresultsappearontheResultspanel.For moreinformation,seeViewingtheResultsoftheServiceonpage 275. Iftheserviceexperiencesanerror,anerrormessagedisplays.ClickDetailsinthe messageboxtoviewthecallstackandthestateofthepipelinewheretheerror occurred.Foradditionalinformationabouterrorsthatoccurwhiletestinga service,seeRunTimeExceptionsonpage 277.

Working in Debug Mode

WhenyouuseDevelopertoexecuteaserviceusingtheRunorRun In Browsercommands, itexecutesasanormalservice.Thatis,theserverdoesnotexecuteitanydifferentlythan itwouldifanyotherclientrequestedit.However,Developeralsoallowsyoutotesta serviceindebugmode,amodethatallowsyoutomonitortheexecutionpathofaflow serviceand/ormovethroughitsstepsoneatatime. Whenyourunaflowserviceindebugmode,itisexecutedinaspecialwaythatreturns resultsandotherdebugginginformationbacktoDeveloperaftereachstep. Note: Youcanonlydebugoneflowserviceatatime.

webMethods Developer Users Guide Version 7.1.1

281

11 Testing and Debugging Services

Entering Debug Mode

Youautomaticallyenterdebugmodewhenyouselectanyofthefollowingcommands fromtheTestmenu: Command Trace Description Executesflowstepsoneafteranothertotheendoftheserviceand visuallymarksstepsastheyexecute.Forinformationaboutusing thiscommand,seeUsingtheTraceToolsonpage 284. Executesflowstepsoneafteranotheruptoaspecifiedpointand visuallymarksstepsastheyexecute.Forinformationaboutusing thiscommand,seeUsingtheTraceToolsonpage 284. Executesflowstepsoneafteranothertotheendoftheserviceand visuallymarksstepsastheyexecute,includingstepsinchildflows. Forinformationaboutusingthiscommand,seeTracingintoa ChildFlowonpage 285. Executesthenextflowstepandthenhalts.Forinformationabout usingthiscommand,seeUsingtheStepToolsonpage 286. OpensachildfloworaMAPstepsothatyoucandebugthe individualflowstepswithinit.Forinformationaboutusingthis command,seeSteppingthoughaChildFlowonpage 287and UsingtheStepToolswithaMAPSteponpage 288.

Trace to Here

Trace Into

Step Step Into

Important! Thedebugcommandsareonlyavailableforflowservices.WhenaJava serviceisselected,thesecommandsarenotavailable. Whenyoufirstenterdebugmode,processingalwaysstartsfromthefirststepintheflow service.Completedstepsaremarkedwithagrayoutline.Astepthatisinprocessoris thenextinlinetobeprocessedismarkedwithagreenoutline.Whenyoustepthougha flowserviceoryouhaltexecutionusingabreakpointortheTrace to Herecommand,the greenoutlineindicateswhichstepwillexecutewhenyouresumeprocessing. Tip! YoucanremovethegrayandgreentracelinesbyusingtheTestResetcommand. Note,however,thatthiswillalsoendyourdebuggingsession. ThefollowingexampleshowsaflowservicethatisbeingexecutedusingtheStep command.Asyoucansee,theBRANCH on PaymentTypestephasthreetargets.Thegray outlineshowswhichpathwasexecuted.ThegreenoutlineindicatesthatBRANCH on /AuthorizationCodeisthestepthatwillexecutewhenthenextStepcommandisperformed.

282

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Debug mode visually shows you the services execution path

This BRANCH target was executed with its respective nested steps. The results of this step are currently on the Results panel. This step will be executed next.

Combining the Step and Trace Commands in Debug Mode

Onceyouenterdebuggingmode,youcanswitchamongthedifferentdebugging commandsandexaminecertainsegmentsoftheservicemorecloselythanothers.For example,youmightwanttoexecutethefirstfewstepsofaservicewiththeStep commandandthensimplytracetheremainder.Or,youmightwanttouseTrace to Here to executetoaparticularpointandthenexecutetheremainingflowstepsonestepatatime. Whenyoucombinetechniques,rememberthattheflowstepoutlinedingreenalways indicatesthecurrentpointofexecutionandmarksthenextflowstepthatwillexecute whenyouresumeprocessing.

Resetting Debug Mode

TheTestResetcommandresetsdebugmode.Youmustusethiscommandwhenyou wanttobegindebuggingthesameserviceagainfromthebeginningoftheflow.The followingactionsalsoresetadebuggingsession: ExecutingtheRuncommand RefreshingDeveloperssessionontheserver Editingtheflowservice Theservicethrowsanexception Whenasessionisreset,tracelinesareclearedandthepointofexecutionissetbacktothe topoftheflowservice.

webMethods Developer Users Guide Version 7.1.1

283

11 Testing and Debugging Services

Thefollowingactionsdonotresetadebuggingsession: Settingbreakpoints Examiningthecontentsofanyoftheothertabsassociatedwiththeservice SavingorrestoringthecontentsoftheResultspanel

Using the Trace Tools

Ifaflowservicehasacomplexpathofexecution(forexample,itcontainsmany branchingsequences),itisoftenusefultosimplyseewhichpathwastakenwhenthe flowexecuted.Thetracetools,Trace,Trace to Here,andTrace Into,allowyoutodothis. Theyvisuallymarktheflowstepsthatareexecutedwithinaflowservice. If you want to... Tracetotheendoftheservicewithouttracingchildservices (breakpointsareignoredinthismode) Tracetoaspecifiedpointintheservicewithouttracingchild services(breakpointsareignoredinthismode) Tracetotheendoftheserviceorthenextbreakpoint,includingthe pathsofallchildservicesthatthisserviceinvokes Use... Trace Trace to Here Trace Into

Note: Totracethroughatoplevelservice,youmusthaveExecute,Read,andList accesstotheservice.Totracethroughalltheserviceswithinatoplevelservice,you musthaveExecute,List,andReadaccesstoallservicesthatthetoplevelservice invokes.FormoreinformationaboutACLsandthetracetools,seeACLsand Testing/DebuggingServicesonpage 111. To trace to the end of a service 1 2 Opentheservicethatyouwanttotrace. OntheTestmenu,clickTrace.

Iftheserviceisalreadyindebugmode,Developertracestheremainingsteps, startingfromthecurrentpointofexecution(thestepoutlinedingreen.) Iftheserviceisnotindebugmode,Developerstartsthetraceatthetopofthe flow.Ifyouhaveanyunsavedchanges,Developerpromptsyoutosavethose changesbeforeitstartsthetrace.Iftheservicetakesinput,youwillbeprompted foritsinputvalues.

284

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

To trace to a specified point 1 2 Opentheservicethatyouwanttotrace. Intheeditor,selecttheflowstepuptowhichyouwanttotrace.(Developerwilltrace allstepsupto,butnotincluding,theoneyouselect.) Note: Ifthepointtowhichyouwanttotraceresidesinachildoftheservicethat youaretesting,youmustusethebreakpointfeaturetotracetothatpoint.For informationaboutsettingbreakpoints,seeSettingBreakpointsonpage 288. 3 OntheTestmenu,clickTrace to Here.

Iftheserviceisalreadyindebugmode,Developerstartsatthecurrentpointof execution(thestepoutlinedingreen)andtracestotheselectedstep.Ifthe selectedstepisbeforethecurrentpointofexecution,thetracestartsatthetopof theflow. Iftheserviceisnotindebugmode,Developerstartsthetraceatthetopofthe flowserviceandtracestotheselectedstep.Ifyouhaveanyunsavedchanges, Developerpromptsyoutosavethosechangesbeforeitstartsthetrace.Ifthe servicetakesinput,youwillbepromptedforitsinputvalues.

WhenDeveloperreachestheselectedflowstep,ithalts.Atthispoint,youmaydoany ofthefollowing:

ExaminethecontentsoftheResultspanel. Modify,save,and/orrestorethecontentsoftheResultspanel. UseSteporStep Intotoexecutesubsequentflowstepsoneatatime. SelectanotherstepintheflowserviceanduseTrace to Heretotracetothatpoint. SelectTracetotracetheremainderoftheservice. SelectResettoclearthedebuggingsessionandresetthestartingexecutionpoint tothetopoftheservice.

Tracing into a Child Flow

Manytimes,theserviceyouaredebugginginvokesotherflowservices(childservices).In thesecasesitisusefultotracetheexecutionpathsofthechildservicesaswellasthe parentthatyouaretesting.YoudothiswiththeTrace Intocommand. WhenyouinitiateatracewithTrace Into,Developerautomaticallyopensandtracesthe individualstepsineverychildflowthattheparentinvokes,includingthechildrenofthe childservicesifthereareany.

webMethods Developer Users Guide Version 7.1.1

285

11 Testing and Debugging Services

To trace into a child service 1 2 Opentheparentservicethatyouwanttotest. OntheTestmenu,clickTrace Into.

Iftheserviceisalreadyindebugmode,Developerstartsthetraceatthecurrent pointofexecution(thestepoutlinedingreen)andtracestheserviceandits childrenuntilitreachesabreakpointortheendoftheflow. Iftheserviceisnotindebugmode,Developerstartsthetraceatthetopofthe flowandtracestheserviceanditschildrenuntilitreachesabreakpointortheend oftheflow.Ifyouhaveanyunsavedchanges,Developerpromptsyoutosave thosechangesbeforeitstartsthetrace.Iftheservicetakesinput,youwillbe promptedforitsinputvalues.

Using the Step Tools

YouusetheStep,Step Into,andStep OutcommandsontheTestmenutointeractively executeaflowserviceoneflowstepatatime.Steppingthroughaflowisaneffective debuggingtechniquebecauseitallowsyoutoexamine(andoptionallymodify)thedata inthepipelinebeforeandaftereachstep.Additionally,ifyouaretryingtoisolatean error,stepmodecanquicklyhelpyoupinpointtheoffendingflowstep. If you want to... Executethecurrentflowstep(theonewiththegreenoutline) Openachildflowsothatyoucandebugtheindividualflowsteps withinit Returntotheparentflowfromachildthatyouhavesteppedinto Use... Step Step Into Step Out

Note: Tostepthroughatoplevelservice,youmusthaveExecute,Read,andList accesstotheservice.Tostepthroughalltheserviceswithinatoplevelservice,you musthaveExecute,List,andReadaccesstoallservicesthatthetoplevelservice invokes.FormoreinformationaboutACLsandthesteptools,seeACLsand Testing/DebuggingServicesonpage 111. Note: Whenyoustepintoachildflow,Developerdisplaysthechildflowintheeditor. Notethatatanypointwhilesteppingthroughaflowservice,youcandoanyofthe following: ExaminethecontentsoftheResultspanel. Modify,save,and/orrestorethecontentsoftheResultspanel. SelectastepintheflowserviceanduseTrace to Heretotracetothatpoint.

286

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

SelectTracetotracetheremainderoftheservice. SelectResettoclearthedebuggingsessionandresetthestartingexecutionpointto thetopoftheservice. To step through a flow service 1 2 Opentheservicethatyouwanttostepthrough. OntheTestmenu,clickStep.

Iftheserviceisalreadyindebugmode,Developerexecutesthecurrentstep(the stepoutlinedingreen)andthenstops. Iftheserviceisnotindebugmode,Developerentersdebugmodeandselectsthe firststepintheflowservice.Toexecutethatflowstep,selectStepagain.Ifyou haveanyunsavedchanges,Developerpromptsyoutosavethosechangesbefore itentersdebugmode.Iftheservicetakesinput,youwillbepromptedforitsinput values.

Stepping though a Child Flow

Manytimes,theflowserviceyouaredebugginginvokesotherflowservices(child services).Inthesecasesitisusefultostepthroughtheindividualflowstepswithina childservice,too.YoudothiswiththeStep Into andStep Outcommands. To step into and out of a child flow 1 Selecttheparentflowserviceandsteportracetotheflowstepthatinvokesthechild flow.SeeTostepthroughaflowserviceonpage 287orTotracetoaspecified pointonpage 285ifyouneedproceduresforthisstep. OntheTestmenu,clickStep Into.Developeropensthechildflowserviceandselects (butdoesnotexecute)thefirststep. OntheTestmenu,clickSteptoexecutethefirststepinthechildservice.Repeatthis stepforeachflowstepthatyouwanttoindividuallyexecutewithinthechild. Ifyouwanttoreturntotheparentflowservicewithoutsteppingthroughtheentire child,clickStep OutfromtheTestmenu.Thiscommandwilltracetheremainingsteps inthechildflow,returntotheparent,andthenselect(butnotexecute)thenextstepin theparentflow. Notes:

2 3 4

Whileyouaredebuggingthechild,youmayuseTrace to Hereorsetabreakpoint toexecuteuptoparticularpointinthechild. IfyouselectTraceorTrace Intowhileyouaredebuggingthechild,Developertraces theremainingstepsinthechildandreturnstotheparentautomatically. IfyouselectSteponthelaststepinthechildflowservice,Developer automaticallyreturnsyoutotheparent.

webMethods Developer Users Guide Version 7.1.1

287

11 Testing and Debugging Services

YoucanuseStep Intotostepintoachildflowthatisnestedwithinachildthatyou havesteppedinto. IfyouselectStep Intoonastepthatisnotaflowservice,Stepisexecuted.

Using the Step Tools with a MAP Step

YoucanusetheStep IntoandStep Outcommandstodebugindividualtransformersina MAPstep. To step into and out of a MAP step 1 SelecttheparentservicethatcontainstheMAPstepandthensteportracetotheMAP step.(Thatis,maketheMAPstepthecurrentflowstep.Developerindicatesthisby outliningthestepingreen.)SeeTostepthroughaflowserviceonpage 287orTo tracetoaspecifiedpointonpage 285ifyouneedproceduresforthisstep. OntheTestmenu,clickStep Into.DeveloperselectsonthePipelinetab(butdoesnot execute)thefirsttransformerintheMAPstep. OntheTestmenu,clickSteptoexecutethefirsttransformer.Repeatthisstepforeach transformerthatyouwanttoindividuallyexecutewithintheMAPstep. IfyouwanttoreturntotheparentwithoutsteppingthroughtheentireMAP,select Step OutfromtheTestmenu.ThistracestheremainingtransformersintheMAP, returnstotheparent,andselects(butdoesnotexecute)thenextstepintheparent flow. Notes:

2 3 4

IfyouselectTraceorTrace IntowhileyouaredebuggingtheMAP,Developertraces theremainingstepsintheMAPandreturnstotheparentautomatically. IfyouselectSteponthelasttransformerintheMAP,Developerautomatically executesthattransformerandreturnsyoutotheparentflow. YoucanuseStep Intotostepintoatransformerthatisaflowservice. IfyouselectStep Intoonatransformerthatisnotaflowservice,Stepisexecuted.

Setting Breakpoints
Abreakpointisapointinaflowservicewhereyouwantprocessingtohaltwhenyou executethatflowservicewithcertaindebugmodes.Breakpointscanhelpyouisolatea sectionofcodeorexaminedatavaluesataparticularpointintheexecutionpath.For example,youmightwanttosetapairofbreakpointsbeforeandafteraparticular segmentofaflowsothatyoucanexaminethepipelineontheResultspanelbeforeand afterthatsegmentexecutes.

288

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Whenworkingwithbreakpoints,keepthefollowingpointsinmind: Breakpointsarenotpersistent.TheyexistonlyduringthelifeoftheDeveloper sessiononthecurrentserverinwhichyousetthem.WhenyoucloseDeveloperor refreshthesessiononthecurrentserver,yourbreakpointsarecleared.(Notethat resettingdebugmodedoesnotclearyourbreakpoints.) BreakpointsarealsolocaltoyourDevelopersessiononthecurrentserver. Breakpointsthatyousetonyourmachinedonotaffectotherdevelopersoruserswho mightbeexecutingordebuggingservicesinwhichyouhavesetbreakpoints. BreakpointsareonlyrecognizedwhenyouexecuteaservicewiththeTrace Into commandfromDeveloper.Ifyouexecuteaserviceusinganyoftheothertestingor debuggingcommands,breakpointsareignored. IfyouarecachingservicesbyusingtheGeneral areaoftheOptionsdialogbox,and yourflowservicehasabreakpoint,youcannotclearthecacheoftheflowserviceuntil thebreakpointisremoved.Formoreinformationaboutcaching,seeConfiguringa ServicesUseofCacheonpage 131. Tosetabreakpointinaservice,youmusthaveReadaccesstoaservice.However,if theserviceisinvokedwithinanotherservice(atoplevelservice)towhichyouhave Readaccess,youcansetabreakpointontheservicewithinthetoplevelservice.

What Happens When a Breakpoint Is Encountered?

Whenyouexecuteaservicethatcontainsabreakpointorcallachildservicethatcontains abreakpoint,theserviceisexecutedupto,butnotincluding,thedesignatedbreakpoint step.Atthispoint,processingstopsandwillnotresumeuntilyouselectanotheroneof Developersdebuggingcommands.(Remember,ifyouwantDevelopertostopat subsequentbreakpoints,youmustselecttheTrace Intocommand.) To set a breakpoint on a flow step 1 2 3 Opentheflowserviceinwhichyouwanttosetabreakpoint. Intheeditor,selectthestepthatwillfunctionasthebreakpoint.(Duringdebugging, processingwillhaltimmediatelybeforethisstep). OntheTest menu,clickSet Breakpoint.Thestepsiconturnsred,indicatingthatitisa breakpoint. To clear a breakpoint from a flow step 1 2 Opentheflowserviceinwhichyouwanttoclearabreakpoint. Intheeditor,selectthebreakpointstep.

webMethods Developer Users Guide Version 7.1.1

289

11 Testing and Debugging Services

OntheTest menu,clickClear Breakpoint.Thestepsiconreturnstoitsnormalcolor, indicatingthatitisnolongerabreakpoint. OR OntheTestmenu,clickBreakpointstodisplaythecurrentlistofbreakpointsonthe currentserver. Inthelist,selectthebreakpointthatyouwanttoclear. ClickRemove.

1 2 3

Setting Breakpoints on Transformers

YoucansetabreakpointonatransformerinaMAPstep.Whenyouexecuteaservice thatcontainsabreakpointorcallsaservicethatcontainsabreakpointonatransformer, theserviceisexecutedupto,butnotincluding,thedesignatedbreakpointtransformer. Note: TransformersinaMAPstepexecuteinanarbitraryorder.Youcannotassumean orderofexecution.Consequently,someofthetransformersintheMAPstepmight executebeforeDeveloperreachesthebreakpoint,evenifthetransformersappear belowthebreakpointonthePipelinetab.Likewise,transformersabovethebreakpoint mightnotexecutebeforethebreakpointisencountered.(Thesewillexecutewhenyou resumetracing.)Executedtransformershaveagrayoutline. To set a breakpoint on a transformer 1 2 3 4 Opentheflowserviceinwhichyouwanttosetabreakpoint. Intheeditor,selecttheMAPstepcontainingthetransformerthatwillfunctionasthe breakpoint. OnthePipelinetab,selectthetransformerthatwillfunctionasthebreakpoint.(During debugging,processingwillhaltimmediatelybeforethistransformer.) OntheTest menu,selectSet Breakpoint.The name,indicatingthatitisabreakpoint. To clear a breakpoint on a transformer 1 2 3 Opentheflowserviceinwhichyouwanttoclearabreakpoint. Intheeditor,selecttheMAPstepthatcontainsthetransformerfromwhichyouwant toclearabreakpoint. OnthePipelinetab,selectthetransformerfromwhichyouwanttoclearabreakpoint. iconappearsnexttothetransformer

290

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

OntheTest menu,clickClear Breakpoint.Developerremovesthe transformername. OR

iconnexttothe

1 2 3

OntheTestmenu,clickBreakpointstodisplaythecurrentlistofbreakpointsonthe currentserver. Inthelist,selectthebreakpointthatyouwanttoclear. ClickRemove.

Viewing a List of Breakpoints

Usethefollowingproceduretoviewthelistofbreakpointsthatarecurrentlysetinyour Developersession.Fromthislist,youcanalsoclearand/orgotospecificbreakpoints. To display the list of current breakpoints 1 2 3 OntheTestmenu,clickBreakpoints. Ifyouwanttogotoaspecificbreakpoint,selectitandthenclickGo to Breakpoint. Ifyouwanttoclearabreakpoint,selectitandthenclickRemove. Note: Remember,breakpointsarenotpersistent.TheyonlyexistduringtheDeveloper sessiononthecurrentserverinwhichyousetthem.Whenyourefreshorcloseyour sessiononthecurrentserver,yourbreakpointsarecleared.

Disabling Flow Steps, Transformers, and Conditions

Whentestinganddebuggingservices,youcandisableflowstepsandtransformers.You canalsodisabletheconditionplacedonalinkbetweenvariablesonthePipelinetab.The followsectionsprovidemoreinformationaboutdisablingeachoftheseitems.

Disabling Flow Steps

YouusetheComposeDisable Stepcommandtodisableastepinaflowservice.Stepsthat youdisablearenotexecutedatruntime. DisabledstepsappeardimmedwhenviewedinDeveloper.Ifyoudisableaparentstep (forexample,aLOOPoraBRANCH),itschildrenarealsoautomaticallydisabled.Ifyou disableaMAPstep,thetransformersintheMAPsteparealsoautomaticallydisabled.

webMethods Developer Users Guide Version 7.1.1

291

11 Testing and Debugging Services

Disabled steps are not executed at run time

Disabled steps appear dimmed in the editor.

Disablingastepisusefulinmanytestinganddebuggingsituations.Forexample,you mightwanttodisableoneormorestepstoisolateaparticularsegmentofaflow,similar tothewayyoumightcommentoutasectionofsourcecodeinaprogramyouare testing. Beawarethatdisablingastepsetsapersistentattributethatissavedintheflowservice. Onceyoudisableastep,itremainsdisableduntilyouexplicitlyreenableitwith Developer. Important! Theruntimeeffectofdisablingastepisthesameasdeletingit.Disablinga keysteporforgettingtoreenableadisabledstepcanbreakthelogicofaservice and/orcausetheservicetofail.Developerallowsyoutodisableanystepinaflow service,butitisyourresponsibilitytousethisfeaturecarefully. To disable a step in a flow service 1 2 3 Opentheflowservicethatyouwanttoedit. Intheeditor,selectthestepthatyouwanttodisable. OntheComposemenu,clickDisable Step. Thestepdims,indicatingthatitisdisabled. To enable a step in a flow service 1 2 3 Opentheflowservicethatyouwanttoedit. Intheeditor,selectthedisabledstepthatyouwanttoreenable. OntheComposemenu,clickEnable Step.

292

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Disabling Transformers
YoucanalsousetheComposeDisable StepcommandtodisableatransformerinaMAP step.Transformersthatyoudisablearenotexecutedatruntime.Infact,webMethods IntegrationServerdoesnotexecuteanyofthelinksbetweenpipelinevariablesandthe variablesforadisabledtransformer. DisabledtransformersappeardimmedwhenviewedinDeveloper. Disabled transformers are not executed at run time

Transformers that are disabled appear dimmed on the Pipeline tab.

Note: WhenyoudisabletheMAPstep,Developerautomaticallydisablesallofthe transformersinaMAPstep Important! Theruntimeeffectofdisablingatransformeristhesameasdeletingit. Disablingatransformerorforgettingtoreenableadisabledtransformercanbreak thelogicofaserviceand/orcausetheservicetofail.AlthoughDeveloperallowsyou todisableanytransformerorstepinaflowservice,usethisfeaturecarefully. To disable a transformer in a MAP step 1 2 3 4 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheMAPstepcontainingthetransformerthatyouwanttodisable. OnthePipelinetab,selectthetransformeryouwanttodisable. OntheComposemenu,clickDisable Step. Thetransformerdims,indicatingthatitisdisabled.

webMethods Developer Users Guide Version 7.1.1

293

11 Testing and Debugging Services

To enable a transformer in a MAP step 1 2 3 4 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheMAPstepcontainingthedisabledtransformerthatyouwant toenable. OnthePipelinetab,selectthedisabledtransformerthatyouwanttoenable. OntheComposemenu,clickEnable Step.

Disabling a Condition Placed on a Link Between Variables

Whenyoulinkvariablestoeachother,youcanapplyaconditiontothelinkthatconnects thevariables.Atruntime,thisconditionneedstobetrueforthevalueofthesource variabletobecopiedtothetargetvariable.Duringtestinganddebugging,youmight wanttodisableorremovetheconditionfromthelinktomakesurethatDeveloper properlycopiesdatabetweenvariables.Bydisablingthecondition,youinstruct Developertoignoretheconditionplacedonthelinkandautomaticallyexecutethelink (copythevaluefromthesourcevariabletothetargetvariable). Disablingtheconditionpreservesthewrittenexpression.Whenyouenablethecondition, youdonotneedtorewritetheexpression. ThePipelinetabusesabluelink(line)toindicatethatproperties(suchasconditionsand arrayindexes)havebeenappliedtothelinkbetweenvariables.Developerretainsthe bluecolorevenwhenyoudisabletheappliedconditiontoremindyouthatproperties havebeenset. To disable a condition placed on a link between variables 1 2 3 4 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheINVOKEorMAPstepthatcontainsthelinkwiththecondition youwanttodisable. OnthePipelinetab,selectthelinkwiththeconditionthatyouwanttodisable. IntheGeneralcategoryofthePropertiespanel,settheEvaluate copy conditionproperty toFalse. To enable a condition placed on a link between variables 1 2 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheINVOKEorMAPstepcontainingthelinkwiththecondition youwanttoenable.

294

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

3 4

OnthePipelinetab,selectthelinkwiththeconditionthatyouwanttoenable. IntheGeneralcategoryofthePropertiespanel,settheEvaluate copy conditionproperty toTrue.

Modifying the Current Pipeline

Duringdebugging,youcanmodifythecontentsofthepipelineandsubmitthose changedvaluestothenextstepintheflowservice.Forexample,ifyouwanttoseethe effectthatdifferentvaluesforavariablehaveontherestoftheservice,youcanmodify thevaluesinthepipelinetemporarilyandcontinuedebugging.Youcanalsodropvalues fromthepipeline.Thisfunctionalityisusefulfordebugging. Whenmodifyingthepipeline,keepthefollowingpointsinmind: Youcanonlymodifythepipelinewhenasubsequentstepintheserviceexiststo whichtopassthepipelinevalues.Forexample,ifyouuseTracefortheentireservice, youcannotmodifythevaluesofthepipelineaftertheserviceends.However,ifyou useSteptodebugtheservice,youcanmodifythepipelinevaluesforthenextstepin theservice. YoucannotmodifythevaluesofunconstrainedObjectsandObjectlists.However, youcandropthemfromthepipeline. Youcannotmodifythevaluesofrecursivedocumentsatthetoplevel.However,you canexpandthedocumentandsetvaluesattheindividualelementlevel. Whenyoumodifyvaluesordropvariablesfromthepipeline,thechangesonlyapply tothecurrentdebuggingsession.Theserviceisnotpermanentlychanged. Youcanonlymodifyordropexistingvariables.Youcannotaddnewvariablestothe pipeline. YoucannotusealargereditororhaveapasswordfieldwhenyoumodifyString valuesinthepipeline. To modify values in the current pipeline 1 2 3 4 5 6 UsetheStep,Step Into,orTrace to Herecommandtoloadvaluesintothepipelineforthe currentstep. IntheResultspanel,selectthenameofthevariableforwhichyouwanttochangethe value. RightclickandselectModify Value. IntheModifyValuedialogbox,typethenewpipelinevalueforthevariable. ClickOK.ThevalueischangedintheResultspanel. Todebugtherestoftheservicewiththenewpipelinevalue,usetheStep,Step Into,or Trace to Herecommand.Keepinmindthatthevalueisonlychangedforthecurrent debuggingsession;itisnotchangedpermanently.

webMethods Developer Users Guide Version 7.1.1

295

11 Testing and Debugging Services

To drop values from the current pipeline 1 2 3 4 UsetheStep,Step Into,orTrace to Herecommandtoloadvaluesintothepipelineforthe currentstep. IntheResultspanel,selectthenameofthevariablethatyouwanttodropfromthe pipeline. RightclickandselectDrop.ThevariabledisappearsfromtheResultspanel. Todebugtherestoftheservicewiththedroppedpipelinevalue,usetheStep,Step Into,orTrace to Herecommand.Keepinmindthatthevalueisonlydroppedforthe currentdebuggingsession;itisnotdroppedpermanently.

Saving and Restoring the Pipeline

Becausethepipelinecontainsthedatathataserviceoperatesagainst,theabilitytosave andrestorethepipelinewhenyouaredebuggingaserviceissomethingyoumay frequentlywanttodo.Forexample,ifaserviceisfailingintermittentlyatruntime,you maywanttoinsertstepstosavethepipelineatvariouspointsintheservicesoyoucan captureandexaminethedatathatitwasrunningagainstafterafailure.

Saving the Results

Youcansavethepipelinetoafile,whichyoucanusetorestorethepipelinetoitscurrent stateatalaterpointintime.Thisisusefulwhenyouwanttotestanotherserviceagainst thecurrentsetofpipelinevaluesorifyouwanttorestorethepipelinetothisexactstate laterinthedebuggingprocess.Therearetwowaystosavethecontentsofthepipeline: YoucanmanuallysavethecontentsoftheResultspanelwhenyourunordebuga serviceusingDeveloper. Youcanprogrammaticallysavethepipelineatruntimebyinvoking pub.flow:savePipelineToFileatthepointwhereyouwanttocapturethepipeline. Whenyousaveapipeline,itissavedinafileinXMLformat.Thefileyoucreatecanbe usedto: ManuallyloadthepipelineintoDevelopersResultspanel. Dynamicallyloadthepipelineatruntimeusingthe pub.flow:restorePipelineFromFile service. LoadasetofinputvaluesintotheInputdialogboxwhentestingaservicewith Developer.

296

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Youcanviewapipelinefilewithanordinarytexteditor.Whensavingthepipeline,keep thefollowingpointsinmind: OnlyXMLcodablevariablesaresaved.Thisincludes,Strings,Stringlists,String tables,documents,anddocumentlists.VariablesthatarenotXMLcodablearenot saved. Emptyvariablesandnullvariablesaresaved.

Saving the Contents of the Results Panel

UsethefollowingproceduretosavethecontentsoftheResultspaneltoapipelinefile. To save the contents of the Results panel 1 2 DisplaytheResultspanelandclickanywherewithinit. Rightclickandselectoneofthefollowingcommands: To Savethefiletoyourlocalfilesystem. Note: Ifyouintendtousethepipelinefiletodynamically restorethepipelineusingpub.flow:restorePipelineFromFile, useSave Pipeline to Servertosavethefiletotheserver(see below). SavethefiletothepipelinedirectoryonwebMethods IntegrationServer. Selectthiscommandifyouwanttousethefileto dynamicallyrestorethepipelineatruntimeusingthe pub.flow:restorePipelineFromFile service. 3 Dependingonyouractioninthepreviousstep,dooneofthefollowing: If you selected Save Pipeline Locally Save Pipeline to Server Do this to specify the file name Selectthedirectoryinwhichyouwantthefilesavedand assignanametothefile. Specifythenameofthefileinwhichyouwantthepipeline saved.Bydefault,Developersavesthefileto IntegrationServer_directory\pipeline,whichiswherethe restorePipelineFromFileserviceexpectspipelinefiles.Ifyou specifyarelativepathinthefilename,thepathis understoodtoberelativetothepipelinedirectory. Save Pipeline to Server Select this command Save Pipeline Locally

webMethods Developer Users Guide Version 7.1.1

297

11 Testing and Debugging Services

Saving the Pipeline at Run Time

Usethefollowinggeneralstepstosavethepipelineprogrammatically.Youcanusethis techniquetocapturethepipelinefromaflowserviceorwithinaJavaservice. 1 2 3 Opentheservice. Invokepub.flow:savePipelineToFileatthepointwhereyouwanttosaveacopyofthe pipeline. Setthefollowingparameter: Key filename Description Astringthatspecifiesthenameofthefiletowhichyouwantthe filesaved.Ifyoudonotspecifyafullyqualifiedpath,thefileis savedrelativetoIntegrationServer_directory\pipeline.

4 5

Savetheservice.(IfyouareusingyourownIDE,youwillneedtorecompilethe service,reregisteritontheIntegrationServer,andreloaditspackage.) Executetheservice.

Foradditionalinformationaboutpub.flow:savePipelineToFile,seethewebMethodsIntegration ServerBuiltInServicesReference.

Restoring the Pipeline

Pipelinevaluesthatyouhavesavedtoafileinthefollowingwayscanbeusedtorestore thepipeline: FromtheDevelopersResultspanelwiththeSave Pipelinecommands. Withthepub.flow:savePipelineToFileserviceatruntime. FromtheInputdialogboxwhenyouaretestingaservicewithDeveloper. Restoringapipelineisusefulwhenyousimplywanttoinspectthevaluesinaparticular pipelinefile(perhapsonethatcontainsthepipelinefromafailedservice).Additionally,it isusefulinmanytestingsituations.Forexample,youcanuseittoreplacetheexisting pipelinewithadifferentsetofvalueswhensteppingthoughaflowservicewiththe debuggingtools. Therearetwowaystorestorethecontentsofthepipeline: YoucanmanuallyloadthesavedpipelineintotheResultspanelinDeveloper. Youcanprogrammaticallyloadasavedpipelineatruntimebyinvoking pub.flow:restorePipelineFromFileatthepointwhereyouwanttomodifythepipeline.

298

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Loading a Saved Pipeline into the Results Panel

UsethefollowingproceduretoloadapipelinefileintotheResultspanel. WhenyouloadapipelinefileintotheResultspanel,thecontentsofthepipelinefile completelyreplacesthecurrentpipeline.Ifyouwanttomergethecontentsofthefilewith theexistingpipeline,usethepub.flow:restorePipelineFromFileserviceinsteadandsetitsmerge parametertotrue.Forprocedures,seeLoadingaSavedPipelineatRunTimeon page 299. To load a pipeline file into the Results panel 1 2 DisplaytheResultspanel.(Ifyousimplywanttoinspectasavedpipeline,createa new,emptyflowserviceanddisplayitsResultspanel.) Rightclickandselectoneofthefollowingcommands: To... Loadapipelinefilefromyourlocalfilesystem Loadafilethatresidesinthedefaultpipelinedirectory onwebMethodsIntegrationServer 3 Select... Restore pipeline locally Restore pipeline from Server

Dependingonyouractioninthepreviousstep,dooneofthefollowing: If you selected... Restore Pipeline Locally Restore pipeline from Server Do this to specify the file name... Selectthefilethatyouwanttoload. Specifythenameofthefilethatyouwanttoload. Developerretrievesthefilefrom IntegrationServer_directory\pipeline.

Loading a Saved Pipeline at Run Time

Usethefollowinggeneralstepstoloadapipelinefileprogrammatically.Youcanusethis techniquefromaflowserviceorfromaJavaservice. 1 2 Opentheservice. Invokepub.flow:restorePipelineFromFileatthepointwhereyouwanttoloadthepipeline file.

webMethods Developer Users Guide Version 7.1.1

299

11 Testing and Debugging Services

Setthefollowingparameters: Key filename Description AStringthatspecifiesthenameofthepipelinefile.Ifyoudonot specifyafullyqualifiedpath,thefileisassumedtoberelativeto IntegrationServer_directory\pipeline.Forexample,ifyouset filenametobadPipeline.xml,restorePipelineFromFileexpectsto findthatfilein IntegrationServer_directory\pipeline\badPipeline.xml. AStringthatspecifieswhetheryouwantthecontentsofthefile toreplaceorbemergedwiththeexistingpipeline. Set merge to...
false

merge

To... Replacetheexistingpipelinewiththeone fromthefile. Mergethecontentsofthefileintotheexisting pipeline.

true

4 5

Savetheservice.(IfyouareusingyourownIDE,youwillneedtorecompilethe service,reregisteritonwebMethodsIntegrationServer,andreloaditspackage.) Executetheservice.

Foradditionalinformationaboutpub.flow:restorePipelineFromFile,seethewebMethods IntegrationServerBuiltInServicesReference.

Other Debugging Techniques

Thissectiondescribesadditionaltoolsandtechniquesyoucanusetoobtainruntime informationthatisusefulfordebuggingaservice.

Using the Servers Debug Facility

webMethodsIntegrationServermaintainsalogfileinwhichitrecordsinformationabout activityontheserver.Thislogfileresidesin: IntegrationServer_directory\logs\serveryyyymmdd.log Thelogcontainsinformationaboutactionsthattheserverexecutes,suchasloading packagesandexecutingservices.TheIntegrationServercreatesoneserverlogperday. Thefollowingexampleshowstheseriesofmessagesthatarepostedtoserverlogwhen theserverisstarted.Notethaterrormessagesarepostedforservicesthattheserver cannotload.

300

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Section of server log from the start-up process

2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 2002-05-24 15:46:58 15:46:58 15:47:00 15:47:03 15:47:10 15:47:10 15:47:11 15:47:14 15:47:14 15:47:14 15:47:14 15:47:15 15:47:18 15:47:20 15:47:20 15:47:21 15:47:21 15:47:21 15:47:21 15:47:22 15:47:22 15:47:22 15:47:22 15:47:22 15:47:26 15:48:07 15:49:12 15:49:14 15:49:15 15:49:30 15:49:35 15:49:36 EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT EDT [ISS.0025.0001C] [ISS.0025.0006C] [ISS.0025.0017C] [ISS.0025.0024C] [ISS.0025.0023C] [ISS.0025.0021C] [ISS.0025.0008C] [ISS.0025.0010C] [ISS.0025.0020C] [ISS.0025.0022C] [ISS.0025.0018C] [ISS.0025.0012C] [ISS.0098.0026D] [ISS.0098.0026D] [ISS.0098.0021D] [ISS.0106.0003D] [ISS.0106.0005D] [ISS.0106.0001D] [ISS.0025.0032C] [ISS.0100.0001C] [ISS.0025.0004C] [ISS.0025.0002C] [ISS.0025.0011C] [ISS.0028.0001C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] [ISS.0028.0005C] Integration Server 6.0 License Manager started Repository Manager started JDBC Connection Manager started Audit Log Manager started ACL Manager started State Manager started Service Manager started Validation Processor started Statistics Processor started Invoke Manager started Cache Manager started Transient Store DefaultStore initialized Transient Store TriggerStore initialized Trigger Dispatcher started Join Message Cache initialized Join Timeout Thread initialized Join Manager initialized Dispatcher initialized Web Container started Flow Service Manager started Package Manager started Package Replicator Manager started Loading packages Loading WmRoot package Loading WmPublic package Loading SGXOrders package Loading WmAdminResource package Loading WmAdmin package Loading WmPKI package Loading Purchasing package Loading Default package

The Contents of the Server Log

Theserverlogfilereceivesoperationalanderrorinformationfromtheserversmajor subsystems.Forexample,thepackagesubsystemlogsinformationintoserverlogwhenit loadsandunloadspackages;theflowmanagerrecordsinformationinthelogwhenit processesaflowservice;theHTTPportrecordsrequeststhatitreceives,andsoforth. Beawarethattheserverdoesnotlogexceptionsthrownbyindividualservices.However, youcancodeyourservicetowriteinformationtotheserverlog,whichcanbeusefulfor debugging.Forinformationaboutwritinginformationtothelogfile,seeWriting InformationtotheServerLogonpage 302.

Server Debug Levels

Theamountandtypeofinformationthatisloggedbytheserverisdeterminedbythe debuglevelunderwhichtheserveroraspecificfacilitywithintheIntegrationServeris operating. Youcanspecifytheserverdebuglevelwhenyoustarttheserver.Thedebuglevelcan rangefromOff,wherenothingislogged,toTrace,inwhichtheserverkeepsanextremely

webMethods Developer Users Guide Version 7.1.1

301

11 Testing and Debugging Services

detailedlog.Formoreinformationabouttheavailablelogginglevels,seethewebMethods LoggingGuide. Thefollowingexampleshowsthestartupcommandyouwouldusetostarttheserverat thetracedebuglevel.

bin\server.bat debug trace

(underWindows)

Ifyoudonotexplicitlysetthedebugswitchwhenyoustarttheserver,thedefaultvalue specifiedinthewatt.debug.levelparameterisused.Thedefaultvalueof watt.debug.levelisInfo. Onceyoustarttheserver,thedebuglevelisset.Whentheserverisrunning,youcan changethedebuglevelusingtheIntegrationServerAdministrator.Ifyoudonotknow thedebuglevelunderwhichyourwebMethodsIntegrationServeroperates,seeyour webMethodsIntegrationServeradministrator. InsteadofrunningtheentireIntegrationServeratahigherdebuglevel,youcanincrease thelogginglevelforaspecificfacilityinIntegrationServer.Forexample,youmightset thelogginglevelfortheServicesfacilitytoTrace.Formoreinformationabout configuringserverlogging,seewebMethodsLoggingGuide. Important! DebuglevelsaboveInfoproducelotsofdetailandcanquicklygeneratean extremelylargelogfile.YoushouldnotrunyourserverattheDebugorTracelevels exceptforbriefperiodswhenyouareattemptingtotroubleshootaparticularissue. Youmayalsooptionallyredirectserverlogmessagestotheconsoleinsteadofafile usingthelog nonestartupswitch.Formoreinformationaboutthisswitchand debuglevels,seeStartingthewebMethodsIntegrationServerinthewebMethods IntegrationServerAdministratorsGuide.

Writing Information to the Server Log

webMethodsIntegrationServerprovidesbuiltinservicesthatallowyoutowrite informationtotheserverlogatruntime.Thesecanbeusefulduringdebuggingbecause youcanusethemtobuildsignalsthatindicatewhethercertainsegmentsofcodewere executed.Youcanalsousethemtorecordtheruntimevalueofaspecificvariable. Therearetwowaystowriteinformationtotheserverlogatruntime.Youcan: Writeanarbitrarymessagetothelogusingpub.flow:debugLog. Dumpthecontentsoftheentirepipelinetothelogusingpub.flow:tracePipeline.

Writing an Arbitrary Message to the Log

Towriteanarbitrarymessagetotheserverlog,youinvokethebuiltinservice pub.flow:debugLog.Youcaninvokepub.flow:debugLogfromaflowserviceoracodedservice (suchasaJavaservice).Whenthisserviceexecutes,itinsertsatextstringthatyouspecify intotheserverlog.Youmightuseittopostprogressmessagesatcertainpointsina service(toindicatewhethercertainsegmentsofcodewereexecuted)ortorecordthe

302

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

valueofaparticularvariableinthelogfilesoyoucanexamineitaftertheservice executes. Thefollowingexampleshowstwoprogressmessages(highlighted)thatwerepostedto theserverlogusingpub.flow:debugLog. Example of messages posted to server log with pub.flow:debugLog
2002-05-28 2002-05-28 2002-05-28 2002-05-28 16:56:12 16:56:53 16:57:56 16:57:56 EDT EDT EDT EDT [ISS.0028.0005C] [ISC.0081.0001E] [ISP.0090.0004C] [ISP.0090.0004C] Loading LogDemo package New LogDemo:demoService begin database update database update completed

Tousepub.flow:debugLog,takethefollowinggeneralsteps: 1 2 Invokepub.flow:debugLogatthepointwhereyouwanttheservicetowriteamessageto theserverlog. Setthefollowingparameters: Key message Description AStringthatspecifiesthemessagethatyouwantwrittentoserverlog. Thiscanbealiteralstringthatyouassigntomessage,however,for debuggingpurposes,itisoftenusefultolinkthisparametertoa pipelinevariablewhoseruntimevalueyouwanttocapture. Optional. AStringthatidentifiesyourservice.TheStringyouspecify willappearinthesecondcolumnofthemessagethatdebugLogwritesto serverlog.Thepurposeofthislabelistoidentifywhichcomponent postedthemessagetothelog. Ifyoudonotassignavaluetofunction,debugLogomitsthelabel. However,keepinmindthatassigningavaluetofunctionwillmakeit easierforyoutolocateyourservicesmessagewhenyouexaminethe logfile.Althoughyoucanassignatextstringofanylengthtofunction, onlythefirst6charactersappearinthelog. level Optional.AStringspecifyingthedebuglevelsunderwhichthis messageistobepostedtothelog.Iftheserverisrunningatadebug levellowerthanthevaluesetinlevel,themessageisnotputintothe logfile. Ifyoudonotspecifylevel,theFatallevelisassumed,whichmeansthat themessageispostedtothelogfileregardlessofwhichdebuglevelthe serverisrunningat.Formoreinformationaboutdebuglevel,see ServerDebugLevelsonpage 301. 3 4 Savetheservice.(IfyouareusingyourownIDE,youwillneedtorecompilethe service,reregisteritonwebMethodsIntegrationServer,andreloaditspackage.) Executetheservice.

function

webMethods Developer Users Guide Version 7.1.1

303

11 Testing and Debugging Services

Foradditionalinformationabout pub.flow:debugLog,seethewebMethodsIntegrationServer BuiltInServicesReference.

Dumping the Pipeline to the Log

Sometimeswhenyouaredebuggingaservice,itisusefultoobtainasnapshotofthe entirepipelineatacertainpointintheflow.Youcandothisbyinvoking pub.flow:tracePipeline,whichputsacopyofthecurrentpipelineinserverlog.Youmay invokepub.flow:tracePipelinefromaflowserviceoracodedservice(suchasaJavaservice). Thefollowingexampleshowsthestartandendpipelinethatwaswrittentotheserverlog withpub.flow:tracePipeline. Example of pipeline written to server log with pub.flow:tracePipeline
2002-05-28 17:37:10 EDT [ISP.0090.0001C] --- START tracePipeline [5/28/02 5:37 PM] -2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 filename = D:\Program Files\IntegrationServer_directory\packages\Examples\pub\goes\catalogue.xml 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Buyer = Caroline Wielman 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Address => 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Street1 = 15788 Cedar Avenue 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 City = Apple Valley 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 State = MN 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 postalCode = 55124 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 0 Order => 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Date = 5/25/2002 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[0] => 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 965003 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = MaxGear D LtWt D Carabiner 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Qty = 300 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Price = 8.50 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Total = 2800 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[1] => 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 896301 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = Hikes 10.5x50 Standard Rope 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Qty = 50 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Price = 175 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Total = 8750 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 1 Items[2] => 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Code = 965007 2002-05-28 17:37:10 EDT [ISP.0090.0008C] 2 Description = MaxGear D Quick Lock

304

webMethods Developer Users Guide Version 7.1.1

11 Testing and Debugging Services

Tousepub.flow:tracePipeline,takethefollowinggeneralsteps: 1 2 Invokepub.flow:tracePipelineatthepointwhereyouwanttheservicetodumpacopyof thepipelinetotheserverlog. Setthefollowingparameters: Key level Description Optional. AStringspecifyingthedebuglevelsunderwhichthepipeline willbepostedtothelog.Iftheserverisrunningatadebuglevellower thanthevaluesetinlevel,thepipelineisnotwrittentothelogfile. Ifyoudonotspecifylevel,Fatalisassumed,whichmeansthatthe pipelineispostedtothelogfileregardlessofwhichdebuglevelthe serverisrunningat.Formoreinformationaboutdebuglevel,see ServerDebugLevelsonpage 301. 3 4 Savetheservice.(IfyouareusingyourownIDE,youwillneedtorecompilethe service,reregisteritonwebMethodsIntegrationServer,andreloaditspackage.) Executetheservice.Foradditionalinformationaboutpub.flow:tracePipeline,seethe webMethodsIntegrationServerBuiltInServicesReference.

webMethods Developer Users Guide Version 7.1.1

305

11 Testing and Debugging Services

306

webMethods Developer Users Guide Version 7.1.1

12

Building Coded Services

308 310 310 311 317 323 327 328

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Java Services Are Organized on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Java Services with Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Java Services with Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Services Using COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Methods from Existing COM and DCOM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

307

12 Building Coded Services

Basic Concepts
InadditiontousingthebuiltinservicesthatwebMethodsIntegrationServerprovides, youcancreatecustomizedservicesinavarietyofprogramlanguages.Thisallowsyouto createalibraryofcustomcodethatcanbeaccessedandexecutedfromaflowserviceor fromaclientapplication. ThischapterdescribeshowtocreateyourownservicesusingJava,C/C++,andVisual Basic. Important! Javaisthenativelanguageforservices.Whenyoucreateservicesinother languages,youmustwrapthemtoappearasaJavaclasstowebMethodsIntegration Server.

The IData Object

TheIDataobjectistheuniversalcontainerthatservicesusetoreceiveinputfromand deliveroutputtootherprograms.Itcontainsanorderedcollectionofkey/valuepairson whichaserviceoperates.AnIDataobjectcancontainanynumberofkey/valuespairs (elements).ThekeysinanIDataobjectmustbeStrings.ThevaluescanbeanyJavaobjects (includingIDataobjects).

Services Take IData Objects as Input and Return IData as Output

Servicestakeone,andonlyone,inputvariable:anIDataobject.Forexample:
public final static void myservice (IData pipeline) throws ServiceException { return; }

Whenaserviceisinvoked,webMethodsIntegrationServerpassestheIDataobjecttoit. TheserviceextractstheactualinputvaluesitneedsfromtheelementswithintheIData object.Forexample:

public final static void myservice (IData pipeline) throws ServiceException { IDataCursor myCursor = pipeline.getCursor(); if (myCursor.first( "inputValue1" )) { String myVariable = (String) myCursor.getValue(); . . } myCursor.destroy(); . . return; }

308

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

AservicereturnsoutputbyinsertingitintoanIDataobject.Anyinformationthatis producedbytheserviceandmustbereturnedtothecallingprogrammustbewrittento theIDataobject.Forexample:

public final static void myservice (IData pipeline) throws ServiceException { IDataCursor myCursor = pipeline.getCursor(); if (myCursor.first( "inputValue1" )) { String myVariable = (String) myCursor.getValue(); . . } myCursor.last(); myCursor.insertAfter( "outputValue1", myOutputVariable ); myCursor.destroy(); return; }

Getting and Setting Elements in an IData Object

GettingdatafromandputtingdataintoIDataelementstakestwosteps.First,youmust positionthecursorattheIDataelement.Next,yougetorsetthedatainthatelement.The classthatyoucanusetopositionacursorinanIDataobjectisIDataCursor.The IDataCursorclasscontainsmethodsforperformingbasiccursoroperationssuchas placingthecursoratthefirst,last,ornextelementintheobject. Afteryoupositionthecursorontheelementwithwhichyouwanttowork,youcanuse thegetValueorsetValuemethodstoreadorwritethevalueofthatelement,respectively. Thisclassalsoprovidesmethodsforinsertingnewelements,gettingkeynames,and deletingelements. Formoreinformationaboutusingthecursorclasses,seethedatapackageinthe webMethodsIntegrationServerJavaAPIReferenceat Developer_directory\doc\api\Java\index.html.

Creating IData Objects

YouusetheIDataFactoryclasstocreateIDataobjects.Forexample:
static IData myIDataObject; static { myObject = IDataFactory.create(); IDataCursor myCursor = myObject.getCursor(); myCursor.insertAfter("VA", new Double("0.045")); myCursor.insertAfter("MD", new Double("0.05")); myCursor.insertAfter("DE", new Double("0.0")); }

FormoreinformationaboutusingtheIDataFactoryclass,seethedatapackageinthe webMethodsIntegrationServerJavaAPIReferenceat: Developer_directory\doc\api\Java\index.html.

webMethods Developer Users Guide Version 7.1.1

309

12 Building Coded Services

Building Services Using Java

SinceJavaisthenativelanguageofservices,itistheeasiestlanguageinwhichtobuilda service. webMethodsDeveloperprovidesanIntegratedDevelopmentEnvironment(IDE)that youcanusetocreate,compile,andpublishJavaservices.TheIDEautomatically generatesanappropriatelystructuredsourcefilethatyousimplyfillinusingthebuilt ineditor.Whenyousavethesourcefile,theIDEautomaticallycompilesitandregistersit ontheserver. AlthoughDevelopersIDEisusefulforcreatingsmall,simpleservices,youmaywantto useyourownJavaIDEtobuildlargeservices.WhenyouuseyourownIDE,youmust createallofthecodeyourself,andmanuallycopyandregistertheclassfileontheserver. webMethodsIntegrationServerprovidesutilitiestopublishservicesyouwriteinyour ownIDE.FormoreinformationaboutcreatingJavaserviceswithoutusingDeveloper, seeBuildingJavaServiceswithYourOwnIDEonpage 317.

How Java Services Are Organized on the Server

AJavaserviceisapublicstaticmethodinaJavaclassfileonwebMethodsIntegration Server.Javaservicesfollowasimplenamingscheme: TheservicenamerepresentstheJavamethodname. TheinterfacenamerepresentsthefullyqualifiedJavaclassname. SinceJavaclassnamescannotcontainthe.character,servicesthatresideinnested foldersareimplementedinaclassthatisscopedwithinaJavapackage.Forexample,a servicenamedrecording.accounts:createAccount ismadeupofaJavamethodcalled createAccountinaJavaclasscalledaccountswithintherecordingpackage. AllJavaservicesthatresideinthesamefolderaremethodsofthesameclass. WhenyoubuildaJavaservicewithDeveloper,itautomaticallycombinesyourservice intotheclassfileassociatedwiththefolderinwhichyoucreatedit.However,ifyoubuild aJavaserviceinyourownIDE,youwillneedtoaddtheclassfiletotheserveryourself. And,ifyouwantthatservicetoberecognizedbyDeveloper,youmustinsertspecial commentcodeinyoursourcecode.

310

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Building Java Services with Developer

ThefollowingdescribesthebasicstagesinvolvedincreatingaJavaservicewith Developer.
Stage 1

Specify the inputs and outputs of the service. Thisstageisoptional,but recommended.Duringthisstage,youdefinetheservicesinputsand outputs(ifyouknowthese)inDevelopersIDE.Forinformationabout thisstage,seeGeneratingJavaCodefromServiceInputandOutput Parametersonpage 315. Create the Java service using Developer. Duringthisstage,youwriteyour programinDevelopersIDE.Forinformationaboutthisstage,see CreatingaJavaServicewithDevelopersIDEonpage 314. Specify the services run-time parameters. Duringthisstage,youassign parametersthatconfiguretheruntimeenvironmentforthisservice.For informationaboutthisstage,seeSettingRunTimeOptionsforaJava Serviceonpage 317.

Stage 2

Stage 3

BeforeyoucreateaJavaservice,youmust: Make sure the package in which you want to create the service already exists. Ifthepackage doesnotalreadyexist,useDeveloperortheIntegrationServerAdministratorto createit.Fordetails,seeCreatingaPackageonpage 72. Make sure the folder in which you want to create the service already exists. Ifthefolderdoes notalreadyexist,useDevelopertocreateit.Fordetails,seeCreatingNewElements onpage 41. Make sure that all Java and C services are unlocked or locked by you in the folderinwhichyou wanttocreatethenewservice.Fordetails,seeLockingJavaandC/C++Serviceson page 91. Important! AllJavaservicesthatbelongtothesamefolderresideinthesameJavaclass file.Thisclasshasthesamenameasthefolder.

Using the Developer IDE

IntheDeveloperIDE,youusetheJavaserviceeditoranditsSharedtabtocreateyour sourcecode.

The Java Service Editor

YouusetheJavaserviceeditortobuildthebodyofyourprogram.Itislikeatemplateyou fillinwithcustomJavacode.Standardblocksofrequiredcodeappearintheshaded areasatthetopandbottomofthetab.Youcannotalterthecodeintheseareas.

webMethods Developer Users Guide Version 7.1.1

311

12 Building Coded Services

The Java service editor is like a template for building a service

Developer automatically generates required code for you.

TherequiredcodeatthetopoftheJavaserviceeditordefinesastaticandfinalmethod withasingleinputparameter:anIDataobject.Theblockofrequiredcodeatthebottom returnsthepipelinetothecaller. WhenyoubuildaJavaservice,youtype(orpaste)yourcodeinthetextboxintheJava serviceeditor.Thefollowingexampleshowsaservicethatgetstwovaluesfromthe pipelineandusesthemtocomputeasalestax.Itputsthecomputedtaxintothepipeline. You use the Java service editor to write the body of your service

Type your code in here.

312

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

The Shared Tab

YouusetheSharedtabtothespecifycommon(thatis,shared)attributesofthisclass.This includesthesuperclassandinterfacedeclarations,requiredimports,andmember variablesthataresharedbutnotexposedasservices.Thecodeonthistabissharedbyall servicesinthisfolder. You use the Shared tab to specify the common attributes of the class

TheExtendsfieldallowsyoutospecifyasuperclassfortheimplementation.Youarenot requiredtospecifyasuperclass. Note: Itisuseful,butnotnecessary,toextendtheclass com.wm.app.b2b.server.Service.Thisclassincludesstaticmethodsforvarious commontasks,likeretrievingthecurrentsessionIDandformattingerrormessages. TheImplementsfieldspecifiesthenamesofJavainterfacesthatyouwanttoimplementin theextendedclass. TheImportsfieldspecifiesthenamesofadditionalJavapackageswhoseclassesare availabletothecurrentclass.WhenyoucreateaJavaservicewithDeveloper,severalJava packagesareautomaticallyaddedtotheimportlist. TheSourcefieldallowsyoutodefineglobalvariablesandmethodsthataresharedbyall servicesinthecurrentfolder.Thisisusefulforbuildingshareddatastructuresand supportingfunctionsthatarenotintendedtobeexposedasservices.Forexample,you mightusetheSourcefieldtodefineanaccounttableandthemethodstousedtoaccessit forasetofservicesthatcreate,get,anddeleteaccountinformation.

webMethods Developer Users Guide Version 7.1.1

313

12 Building Coded Services

Note: Becauseservicesareimplementedasstaticmethods,mostsharedcodeisusually staticaswell.

Creating a Java Service with Developers IDE

ThefollowingproceduredescribeshowtocreatethesourcecodeforaJavaserviceusing DevelopersIDE. To create a Java service with Developer 1 2 3 4 5 6 OntheFilemenu,clickNew. ClickJava ServiceandclickNext. IntheNewJavaServicedialogbox,nexttoFolder,selectthefolderintowhichyou wanttosavethisservice. IntheNamefield,typeanamefortheservice. ClickFinish. Ifyouknowthesetofinputsandoutputsyourprogramuses,specifytheseusingthe Input/Outputtab. Note: YoucanuseDevelopertoautomaticallygenerateJavacodethatgetsand putsthoseinputandoutputvaluesinthepipeline.Formoreinformationabout automaticallygeneratingJavacode,seeGeneratingJavaCodefromService InputandOutputParametersonpage 315. 7 TypethecodeforyourserviceatthetopoftheJavaserviceeditor.Forinformation aboutJavaclassesprovidedwithwebMethodsIntegrationServer,seethewebMethods IntegrationServerJavaAPIReferenceinDeveloper_directory\doc\api\Java\index.html. Ifyouwanttomakeadditionalmethodsand/orstructuresavailabletotheservice, completethefollowingfieldsontheSharedtab. Use this field... Extends To specify... Thenameofthesuperclass(ifany)ofwhichthisclassisan extension.Ifyouspecifyasuperclass,typeitsJavaclassname (fullyqualifiedifnecessary).

314

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Use this field... Implements

To specify... Thenamesofinterfaceswithinthesuperclassthatthisclass implements.Takethefollowingstepstospecifyeachinterfacethat youwanttoimplement: Click toaddanewrowtothelist.

TypethenameofavalidJavaclassname(fullyqualifiedif necessary).Youdonotneedtotypetheimplements keyword. Imports ThenamesofJavapackagesthatthisclassimports.Takethe followingstepstospecifyeachpackagethatyouwanttoimport: Click toaddanewrowtothelist.

TypethenameofavalidJavaclassname(forexample, com.wm.util.Table)orapackageimportspecification(for example,java.util.*).Youdonotneedtotypetheimport keyword. Source 9 Datastructures,methods,andotherJavacodethatyouwantto makeavailabletoallservicesinthisfolder.

WhenyoufinishspecifyingyourcodeintheJavaserviceeditorandontheSharedtab, click onthetoolbartosaveandcompiletheservice.

10 IfDevelopercannotcompiletheservicebecausetheIntegrationServertowhichyou areconnectedcannotfindaJavacompiler,Developerdisplaysanerrormessage.Do thefollowingtoensuretheIntegrationServercanlocatetheJavacompiler: a b c EnsurethataJavacompilerisinstalledonthesamemachineastheIntegration Server. AddthelocationoftheJavacompilertothesystempathofthemachinewherethe IntegrationServerisinstalled. RestarttheIntegrationServer.

Generating Java Code from Service Input and Output Parameters

If,beforeyoustartwritingyourservice,youknowthesetofinputsandoutputsthatit willuse,youcandeclaretheservicesinput/outputparametersfirstandgenerateJava codefromit.Thiscodegetsthespecifiedinputvaluesfromthepipelineandassignsthem tovariablesinyourprogram.Italsoputstheoutputvaluesintothepipeline.

webMethods Developer Users Guide Version 7.1.1

315

12 Building Coded Services

Forexample,iftheInput/Outputtabfortheservicedefinesthefollowingvariablesasinput andoutput: Input Variable Name State Amount Output Variable Name Tax Type String String Type String

DeveloperwillgeneratethefollowingJavacodeforyourservice:
// pipeline IDataCursor pipelineCursor = pipeline.getCursor(); StringState = IDataUtil.getString( pipelineCursor, "State" ); StringAmount = IDataUtil.getString( pipelineCursor, "Amount" ); pipelineCursor.destroy(); // pipeline IDataCursor pipelineCursor_1 = pipeline.getCursor(); IDataUtil.put( pipelineCursor_1, "Tax", "Tax" ); pipelineCursor_1.destroy();

WhenDevelopergeneratescodefromtheserviceinput/outputparameters,itputsthe codeontheClipboard.Fromthere,youcanpasteitintoyourprogram(atthetopofthe JavaserviceeditororinyourownIDE)andmodifyitasnecessary. Note: webMethodsIntegrationServerreturnseverythingthatyourserviceputsinto thepipeline,regardlessofwhatisdeclaredasitsinput/outputparameters.Declaring aservicesinputandoutputparametersdoesnotfilterwhatvariablestheservice actuallyreceivesorreturnsatruntime.Itsimplyprovidesaformaldescriptionof whattheservicerequiresasinputandproducesasoutput. To generate Java code from the service input/output parameters 1 OpentheJavaserviceforwhichyouwanttogeneratecode(ifyouarecreatingthe JavaserviceinyourownIDE,useDevelopertocreateanew,emptyJavaservicethat youwilluseonlyforthepurposeofdeclaringasetofinput/outputparameters). ClicktheInput/Output tabanddefinetheinputsandoutputsforthisserviceiftheyare notalreadyspecified.Formoreinformationaboutdefininginputsandoutputsfora service,seeTodeclareinputandoutputparametersforaserviceonpage 126. IfyouwanttogeneratecodeforasubsetofthevariablesontheInput/Outputtab,select thosevariables. OntheToolsmenu,clickGenerate Code. OntheCodeGenerationdialogbox,selectFor implementing this serviceandclickNext.

3 4 5

316

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Specifythefollowingoptions. Under this... Specification Which fields? Specify... Whetheryouwanttogeneratecodefortheinputvariables,the outputvariables,orboth. Whetheryouwanttogeneratecodeforallvariablesinthe Input/Outputtaborjusttheselectedvariables.

7 8

ClickFinish.DevelopergeneratescodeandplacesitontheClipboard. PastethecontentsoftheClipboardintoyoursourcecode.

Setting Run-Time Options for a Java Service

WhenyoucreateaJavaservicewithDeveloper,youcansetoptionstospecifythe runtimebehavioroftheservice.Theseoptionsdeterminewhether: Theservicerunsinstatelessmode. Theresultsoftheservicearemaintainedincache. Anoutputtemplateisappliedtotheservicewhenitisinvokedbyabrowser. YouspecifytheseoptionsinthePropertiespanel.Forinformationaboutusingthese options,seeSpecifyingRunTimeParametersonpage 129andAssigninganOutput TemplatetoaServiceonpage 127.

Building Java Services with Your Own IDE

TheremaybetimeswhenyouwanttouseyourownIDEinsteadofDevelopertobuilda Javaservice.

The Namespace Directory

Tosuccessfullypublish(install)aJavaservicethatyouhavecreatedwithyourownIDE, youneedtounderstandexactlyhowJavaservicesarestoredonwebMethodsIntegration Server. EachpackageonwebMethodsIntegrationServerhasanamespacedirectory,calledns. Forexample,apackagecalledpurchwouldhavethefollowingdirectorystructure:
IntegrationServer_directory\packages\purch\ns

webMethods Developer Users Guide Version 7.1.1

317

12 Building Coded Services

Thensdirectorycontainsinformationabouttheservicesinthatpackage.Anentryin thenamespacedirectorycorrespondstoaserviceorafolder.Thecontentsofeachentry dependonwhatkindofentryitis. Service entriescontaininformationaboutpropertiesoftheservice(forexample, statelessness),theinputandoutputparametersoftheservice(iftheyhavebeen defined),andJavaorXMLsourceifthesourceisavailableforthatservice. Folder entriescontaininformationaboutthefolder.Thisinformationisusuallylimited toJavasourcefortheservicesinthatfolder,ifavailable. ForJavaservices,informationabouttheserviceisstoredinthenamespacedirectory. However,thecompiledcodeforthatservice(thatis,theclassfile)isstoredinthecode subdirectory.Thefollowingshowsthedirectorypathtotheclassfilesinthepurch package.
IntegrationServer_directory\packages\purch\code\classes\recording\ accounts.class

WhenyouuseDevelopertobuildaJavaservice,itautomaticallyupdatesandmaintains thefolderandserviceinformationinthenamespace.However,ifyoubuildaJavaservice inyourownIDE,youmustuseautilitycalledjcodetocompileyourserviceandgenerate thenecessaryfilesinthenamespace. Important! Althoughyoumaywanttoexaminethecontentsofthenamespace directoriesonyourwebMethodsIntegrationServer,donotmodifythisinformation byhand.OnlymodifythisinformationusingtheappropriatewebMethodstoolsor utilities.Inappropriatechanges,especiallytothensdirectoryoftheWmRoot package,candisableyourserver.

The Source Code Directory

EachpackageontheserverhasasourcesubdirectorythatholdstheJavasourcecodefor thatpackage,ifitisavailable. WhenyoufinishcodingyourJavaservice,saveitssourcefileinthisdirectory(subjectto thenormalJavaconstraintsbasedonpackagedeclarations).Youmustnamethefilesand intermediatedirectoriesaccordingtothenameoftheserviceyouareinstalling.For example,thesourcefilefortherecordingaccountsservicesshowninAppendix E,jcode tagswouldhavethefollowingpath:
IntegrationServer_directory\packages\purch\code\source\recording\ accounts.java

318

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Writing the Source Code for a Service

YourservicemustbewrittenasamethodthattakesanIDataobjectasinput. AJavaserviceisamethodthatispublicandstatic.Ittakesasingleinstanceof com.wm.data.IDataasinputandreturnsoutputinthepipeline.Thefollowingcode showsthebasicframeworkforaJavaservice:
public final static void myservice(IData pipeline) throws ServiceException { return; }

Note: ServicescanthrowServiceException.DonotcallService.throwError. Additionally, YourJavaclassmustimportthefollowingJavapackages. com.wm.data.*; com.wm.app.b2b.server.ServiceException; com.wm.app.b2b.server.Service; YourJavaclassmustbepublic. Forperformancereasons,itisalsorecommendedthatyoumakeyourclassfinal.

Using the webMethods API

webMethodsIntegrationServerprovidesclassesthatyoucanusewithJavaservicesthat youbuild.SeethewebMethodsIntegrationServerJavaAPIReferencein: Developer_directory\doc\api\Java\index.html foradescriptionoftheseclasses.

The Basic Stages

ThefollowingdescribesthebasicstagesinvolvedincreatingaJavaservicewithyour ownIDE.
Stage 1

Create an empty Java service using webMethods Developer (optional).During thisstage,useDevelopertocreateanemptyJavatemplatethatyoucan useaguidelineforcodingyourownservice(seeCreatingaJavaService withDevelopersIDEonpage 314). Specify the input and output parameters (signature) of the service.Duringthis stage,youdefinetheservicesinputsandoutputs(ifyouknowthese).You canuseDevelopertogeneratetheinputandoutputcodethatyoucan pasteintoyourprogram(seeGeneratingJavaCodefromServiceInput andOutputParametersonpage 315).

Stage 2

webMethods Developer Users Guide Version 7.1.1

319

12 Building Coded Services

Stage 3

Create the Java service using your IDE. Duringthisstage,youwriteand compileyourprograminyourIDE.Formoreinformationaboutthis stage,seeWritingtheSourceCodeforaServiceonpage 319. Saving and compiling your code using jcode (optional). Duringthisstage,you canmakeyoursourcecodeavailableforeditingbyDeveloperbyusing thejcodeutility.Forinformation,seeCommentingCodeforthe webMethodsIntegrationServeronpage 320. Publish the service to the webMethods Integration Server.Duringthisstage,you registeryourserviceontheIntegrationServerusingthejcodeutility.For information,seeUsingthejcodeUtilityonpage 321.

Stage 4

Stage 5

Commenting Code for the webMethods Integration Server

ToinstallyourfinishedserviceonthewebMethodsIntegrationServer,youusethejcode utility.Tousethisutilitysuccessfully,youmustannotateyoursourcecodewithjcodetags (speciallyformattedJavacomments)tomarkthefollowingsegmentsofcode: Imports Sharedcodewithintheclass Servicedefinitionsandserviceinputsandoutputs Thefollowingcodefragmentshowsthetagsusedtomarkthebeginningandendofthe importsection.
. . . // --import import // --. . .

<<IS-START-IMPORTS>> --com.wm.data.*; java.util.*; <<IS-END-IMPORTS>> ---

Youusesimilartagstomarkthebeginningandendofothercomponentsinyoursource code.Foracompleteexample,seejcodeExampleinAppendix E,jcodetags.For additionalinformationaboutthejcodeutility,seethenextsectionUsingthejcode Utility.

320

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Using the jcode Utility

Whenyoufinishcreatingandannotatingyoursourcecode,youusethejcodeutilityto compileitandstoreitsserviceinformationinthensdirectory. Jcodeoperatesinthreebasicmodes: Make Mode(forcompilingJavasourcecode). Fragment Mode(forpullingapartsourcecodeandstoringfragmentsandsignaturesin thenamespace). Composite Mode(forrebuildingthesourcefilesfromfragmentsinthenamespace). YoumustusethemakeandfragmentmodestorunyourservicesonwebMethods IntegrationServerandeditthesourcecodefromDeveloper. Important! Beforeyoucancompileaserviceusingjcode,youmustsettheenvironment variableIS_DIRtopointtothedirectoryinwhichwebMethodsIntegrationServeris installed.

Make Mode
Youusethismodetoexaminesourcefilesforoneormorefoldersinapackageand compilethosethathavebeenmodifiedsincetheywerelastcompiled.Thejcodeutility willreportwhichfileswerecompiled,aswellasanyerrorsthatwereencounteredduring theprocess. Tomakeallthecodeinapackage,typethefollowingonthecommandline:
jcode makeall Package

Tocompilesourcefiles,thejcodeutilityinvokestheJDKJavacompiler,javacusingthe followingcommand:
javac classpath pathName d classDir fileList

WherepathNameistheclasspathtouseforthecompile,classDiristhedestination directoryforthecompiledclasses,andfileListisalistofthenamesofsourcefilesto compile. IfyoudonothavetheJDKinstalled,oryouwanttouseanothercompiler,youcanset webMethodsIntegrationServerswatt.server.compilepropertytoanewcommandline (usingtheargumentsdescribedabove).Forinstance,touseIBMsjikes,youwouldset thispropertyto:

jikes +E nowarn classpath pathName d classDir fileList

Fragment Mode
YouusethismodetoupdatetheJavacodefragmentsandservicesignatures(inputand outputparameters)inthenamespacebasedonthejcodetagsinthesourcecodefile.The originalsourcefileisnotmodified,butnamespaceinformationisupdatedandthesource codefortheservicebecomesavailablethroughDeveloper.

webMethods Developer Users Guide Version 7.1.1

321

12 Building Coded Services

Tofragmentallthecodeinapackage,typethefollowingonthecommandline:
jcode fragall Package

Tofragmentonlythecodeforasinglefolder(thatis,asingleJavasourcefile),typethe followingonthecommandline:
jcode frag Package Folder

Composite Mode
Compositemodeistheoppositeoffragmentmode.Youusethismodetobuildasource filebasedonthecodefragmentscurrentlydefinedinthenamespace. Important! Theexistingsourcefile,ifthereisone,isoverwrittenbythesourcefile producedbyjcode.UserlocksinDeveloperwillnotpreventthis,sincethejcode utilityoperatesindependentlyoflockingfunctionality. Toconstructasourcefilebasedonthecurrentinformationinthenamespace,typethe followingonthecommandline:
jcode comp Package Folder

Important! IfyourJavasourcecodecontainsanynonASCIIcharacters,settheproperty watt.server.java.source=Unicode | UnicodeBig | UnicodeLittle.Thedefaultvalue isfile.encoding.WhenUnicodeisset,thecompilecommandlinespecifiedinthe propertywatt.server.compile.unicodeisused.Thedefaultvalueofthispropertyis javac -encoding Unicode -classpath {0} -d {1} {2}.

Other jcode Commands

Becausethetwostepprocessofmakingandfragmentingsourcecodeissocommon, thereareseveralshortcutsbuiltintojcode. Theupdatemodemakesandfragmentsonlysourcefileswhichhavechanged.To update(makeandfrag)allthefolderswithinapackagewhichhavechanged,typethe followingatthecommandline:
jcode update Package

Toupdate(makeandfrag)allthecodeinallpackagesonwebMethodsIntegration Server,typethefollowingatthecommandline:
jcode upall

ToforceamakeandfragonallpackagesonwebMethodsIntegrationServer,type:
jcode hailmary

322

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Building Services Using C/C++

YoucanuseDevelopertobuildasetofstarterfilesyoucanusetocreateaC/C++service. Thesefilesinclude: AJavaservicethatcallsyourCprogram. AC/C++sourcecodetemplatethatyouusetocreateyourCprogram. Amakefileyouusetocompilethefinishedprogramandplaceitontheserver. BeforeyoucreateaC/C++service,youmust: Make sure you have a C compiler installedonwebMethodsIntegrationServerthatyou willusetodevelopandtesttheservice. Make sure the package in which you want to create the service already exists.Ifthepackage doesnotalreadyexist,createitusingwebMethodsDeveloper.Formoreinformation aboutcreatingapackage,seeCreatingaPackageonpage 72.(Ifyoudonothave DeveloperorAdministratorprivileges,askyourserveradministratortodothis.) Make sure the directory for this package contains a code/libs directory. Whenyoucompile yourC/C++service,themakefileplacesthecompiledservice(aDLL)inthis directory.Ifthepackagedoesnotalreadyhaveacode/libsdirectory,createonebefore youbeginbuildingtheservice. Make sure the folder in which you want to create the service already exists. Ifthefolderdoes notexist,useDevelopertocreateit.Fordetails,seeCreatingNewElementson page 41. Declare the input and output parameters for your service in a specification. WhenDeveloper generatesthestartercodeforyourservice,itcreatescodethatextractsthespecified inputvaluesfromthepipelineandassignsthemtovariablesinyourprogram.Italso insertsyourservicesoutputvariablesintothepipeline.Todothis,Developermust knowtheinputandoutputrequirementsofyourservice.Yousupplythisinformation inaspecification.Forinformationaboutcreatingaspecification,seeChapter 9, CreatingISSchemas,ISDocumentTypes,andSpecifications.

webMethods Developer Users Guide Version 7.1.1

323

12 Building Coded Services

Note: IfyouarerunningtheIntegrationServerasanNTservice,youmust completeoneofthefollowing: SettheWindowssystemenvironmentvariablePATHtoinclude IntegrationServer\lib OR CopythewmJNI.dllandwmJNIc.dllfileslocatedinIntegrationServer\lib tothe IntegrationServerdirectory whereIntegrationServeristhedirectoryinwhichyouinstalledthe IntegrationServer.

Generating Files for a C/C++ Service

Ifyouhavesatisfiedtheprerequisitesidentifiedabove,youcanusethefollowing proceduretogeneratethefilesthatyouneedtobuildaC/C++service. To generate C/C++ project files 1 2 3 4 5 OntheFilemenu,clickNew. ClickC ServiceandclickNext. IntheNewCServicedialogbox,inthelistnexttoFolder,selectthefolderintowhich youwanttosavethisservice. IntheNamefield,typeanamefortheserviceandclickNext. SelecttheplatformthatdescribesthemachineonwhichyourwebMethods IntegrationServerisrunning(Developerneedstoknowthisinordertobuildthe rightmakefile).ClickNext. Selectthespecificationforthisservice. ClickFinish.

6 7

The Java Code for a C Service

WhenyoubuildaC/C++service,DeveloperbuildsaJavaservicethatcallsaDLL,which youcreatebywritingaCprogram.TheJavaserviceisthemeansbywhichyourC programisexposedtoclients(ISclientsinvokethisJavaservice,nottheCprogram directly).TheJavaservicealsosuppliestheinput/outputparametersfortheprogram, whichmakesitpossibletoincludeitinaflowserviceandlinkitsinputsandoutputon thePipelinetab.

324

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

DevelopergeneratesalltheJavacodeneededtosuccessfullycallyourCprogram.You mayaddyourowncustomcodetotheCserviceeditororitsSharedtabifyouwantto executeanyspecialproceduresbeforeoraftertheCprogramiscalled,butotherthan that,thisservicecontainseverythingyouneed. The C service editor contains code that calls the Java wrapper for the C program

The Shared tab contains code that loads the library containing the C program

webMethods Developer Users Guide Version 7.1.1

325

12 Building Coded Services

The Input/Output tab declares the input/output parameters for the service

Building the C/C++ Source Code

Developeralsogeneratesasourcecodefileandamakefileforyou.Itplacesthesefilesin thefollowingdirectory:
IntegrationServer_directory\packages\packageName\code\source

ThenamesofthefileswillmatchtheservicenameyouspecifiedinDeveloper. To build the C/C++ source code 1 2 Locatethesourcecodeandmakefiles. Copythesourcecodefiletoanewfile(inthesamedirectory)withthefollowingfile name:

serviceNameImpl.c

Forexample,ifyourservicenameisPostPO,youwouldcopyPostPO.ctoPostPOImpl.c. YoucreatetheprogramintheserviceNameImpl.cfile,nottheoriginalfile.Thisisthe fileinwhichthemakefileexpectstofindyoursourcecode.(Thisstepistakento maintainacopyoftheoriginalsourcefiletowhichyoucanrefer,orrevertbackto, duringyourdevelopment.) 3 EdittheserviceNameImpl.cfileasnecessarytobuildyourservice. Thisfilewillcontaininstructivecommentsthatwillguideyourdevelopment.Youcan alsorefertowebMethodsCAPIforinformationabouthowtousethewebMethods C/C++APItomakethedatainyourserviceavailabletootherservices.Thisfileis locatedinDeveloper_directory\doc\api\c\index.html.

326

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

Editthemakefiletocustomizeitforyourdevelopmentenvironment.Setthe followingpathsettings: Set... JDKDIR SEVRDIR To... TothedirectorythatcontainstheJavaDevelopmentKit. ThedirectoryinwhichwebMethodsIntegrationServeris installed.

Important! ThesourcecodefileserviceName.ccontainscodebasedonthe specificationyouselectedfortheservice.Ifyoueditthespecification,youneedto regeneratethesourcecodefile.DeveloperdoesnotupdatetheserviceName.cfile automatically.Formoreinformationaboutgeneratingsourcecodefilesfora C/C++service,seeGeneratingFilesforaC/C++Serviceonpage 324. 5 Afteryoufinishcodingyourservice,runyourmakefiletocompileit.Followingisa typicalmakecommand:

make f SalesTax.mak

ThemakefilecompilesyourprogramandputsthefinishedDLLinthecode\libs directoryinthepackageinwhichtheserviceresides(ifthisdirectorydoesnotexist whenyourunthemakefile,yourprogramwillnotcompilesuccessfully). 6 Onceyourprogramcompilessuccessfully,restartwebMethodsIntegrationServerto reloadthecode\libsdirectory.Thismakestheserviceavailableforexecutionand allowsyoutotestitwithDeveloper.Fordetailsontesting,seeChapter 11,Testing andDebuggingServices.

Building Services Using COM

TherearetwowaysinwhichyoucanuseCOMobjectswithwebMethodsIntegration Server.Youcan: Invoke methods/properties on existing COM or DCOM objects.webMethodsIntegration ServerincludesbuiltinservicesforinstantiatinganyCOMorDCOMobject registeredonyoursystemandinvokingitsmethodsandproperties.Thisallowsyou touseexistingCOMAPIswritteninVisualBasicorVisualC++withoutwriting lowlevelbridgingcode.Fordetails,seeInvokingMethodsfromExistingCOMand DCOMObjectsonpage 328. Create services using COM. webMethodsIntegrationServerincludeslibrariesforusein yourownVisualBasicorVisualC++code.TheyallowyoutocreateCOMobjectsthat performworkonwebMethodsdatastructures.Theseobjects(compiledintoActiveX DLLsorEXEs)canthenberegisteredasnativeservices,indistinguishablefromtheir Javacounterparts.

webMethods Developer Users Guide Version 7.1.1

327

12 Building Coded Services

Requirements
TousewebMethodsIntegrationServerwithCOMorDCOM,yourwebMethods IntegrationServermustberunningJavaVirtualMachine1.2orlater. Important! IfyoumodifyVisualBasiccodeintendedforusewithwebMethods IntegrationServerlibraries,donotusethedebugmodeintheVisualBasic developmentenvironmenttotestyourcode.(Thedebuggerdoesnotmaintain referencestowebMethodsIntegrationServerlibraries.)Instead,usealoggingfeature inyourdevelopmentenvironmenttotestthecode.

Invoking Methods from Existing COM and DCOM Objects

YoucanusewebMethodsIntegrationServertoaccessmethodsinexistingCOMand DCOMlibrariesthatdonotusewebMethodsIDataobjects.Forexample,youmayhavea COMobjectthatperformsavalidationroutineonaStringandreturnsanencrypted Stringinresponse.Itmaynotbesensibleordesirabletowrapthisobjectwithaserviceif thecomponentissimpleenoughand/orpartofanexisting,unmodifiableapplication.In thesecases,thedispatchservicescanhelp.

Creating the Object

Thewin32.COM.dispatch:createObjectservice(locatedintheWmWin32package)willcreate anobjectgivenaProgramIDortheGloballyUniqueIdentifier(GUID)forthatobject. Youneedtoprovidethisservicewiththefollowinginputs: Name progid OR guid context server user password domain TheGloballyUniqueIdentifier(GUID)oftheobjectthatyouwantto invoke. Thecontextfortheobject,whichisINPROC(DLL),LOCAL_SERVER (EXE),orREMOTE_SERVER(EXE). DCOMonly.TheTCP/IPdomainnameofthemachinewheretheDCOM objectislocated.Forexample,doc.rubicon.comor128.111.222.001. Optional.DCOMonly.Thenameoftheuserinwhichtolaunchthe remoteCOMobject. Optional.DCOMonly.Thepasswordassociatedwithuser. Optional.DCOMonly.TheWindowsdomainassociatedwithuser. Description TheprogramIDoftheobjectthatyouwanttoinvoke.

Note: TheWmWin32packageisdeprecatedforIntegrationServer7.1.

328

webMethods Developer Users Guide Version 7.1.1

12 Building Coded Services

TheservicewillreturnareferencetotheobjectcalledpDispatchorthrowanerrorifthe objectcannotbecreated. Tip! TheWmWin32packageisinstalledwiththeIntegrationServeronMicrosoft Windowsplatformsbut,bydefault,isnotenabled.Toviewthepackageandaccessits serviceswithinDeveloper,firstenableitusingtheIntegrationServerAdministrator.

Invoking the Object

Toinvokemethodsorpropertiesonthisobjectonceyouhavecreatedit,use win32.COM.dispatch:invoke.Youneedtosupplythisservicewiththefollowinginputs: Name pDispatch dispName accessType Description AnobjectreferencepreviouslyobtainedbythecalltocreateObjector obtainedintheresultvalueofapreviouscalltoinvoke. ThenameoftheCOMmethodorpropertythatyouwanttoinvoke. Optional.Thetypeofoperation(METHOD,GET,PUT,PUTREF)tobe performedondispName.IfyouareinvokingaDCOMobject,alwaysset accessTypetoGET.Incorrectsettingofthisparameterwillcausethe invoketofail. IfyouareunsurewhetheradispNameisamethodorproperty,examine thecomponentstypelibraryusingOLEVIEWoraMicrosoft developmentenvironment. params Optional.Anobjectarrayofparameters.ThisisexposedinDeveloperas anarrayofStringsforusability(becauseObjectscannotbemanipulated inDeveloper),butisinrealityanObjectarray.Ifyouneedtopass complexornativetypes,youmayhavetocreatethisvaluewithinyour ownservice.

Iftheinvocationissuccessful,thereturnvalueiscontainedinresult.Iftheresultisan objectvariable,itcanthenbethetargetofsubsequentcallstoinvokebylinkingtheresult topDispatchinthenextinvoke.

webMethods Developer Users Guide Version 7.1.1

329

12 Building Coded Services

330

webMethods Developer Users Guide Version 7.1.1

13

Creating Client Code

332 332 335 337 339 341

Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

331

13 Creating Client Code

Basic Concepts
webMethodsDeveloperenablesyoutoautomaticallygenerateclientcodeinavarietyof languagesandforseveralenvironments.Clientcodeisapplicationcodethatinvokesa serviceonawebMethodsIntegrationServer.Ittypicallyperformsthefollowingbasic tasks: Promptstheuserforinputvalues(ifyourservicetakesinput) Placestheinputsintoaninputdocument(ifyourservicetakesinput) OpensasessiononwebMethodsIntegrationServer Invokesaservice Receivesoutputfromtheservice ClosesasessiononwebMethodsIntegrationServer Displaystheoutputtotheuser TheclientcodethatDevelopergeneratescanserveasagoodstartingpointforyourown development.

Building a Java Client

YoucanuseDevelopertogenerateJavaclientcodethatinvokesaservice.

Assumptions
webMethodsIntegrationServerisrunning. AfullyfunctionalJDKisinstalled.IfyouareusingtheJVMthatwasinstalledwith theIntegrationServer,nofurtheractionisneeded.IfyouareusingadifferentJVM, dothefollowingtoobtainthefilestheIntegrationServerneedstosupportsigned libraries:

332

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

If your runtime JDK is... JDK1.4.*

Do the following... Ensurethattheunlimitedstrengthjurisdictionpolicyfiles (local_policy.jarandUS_export_policy.jar)areinstalledaspartof yourJVMinstallation. Ifthesefilesarenotinstalled,downloadthemasfollows: IfyouarerunningtheSunJDK1.4.*,downloadthefilesfrom http://java.sun.com/j2se/1.4.1/download.html/. IfyouarerunningtheIBMJDK1.4.*,downloadthefilesfrom http://www106.ibm.com/developerworks/java/jdk/security/.

JDK1.5.*

Ensurethattheunlimitedstrengthjurisdictionpolicyfiles (local_policy.jarandUS_export_policy.jar)areinstalledaspartof yourJVMinstallation. Ifthesefilesarenotinstalled,downloadthemasfollows: IfyouarerunningtheSunJDK1.5.*,downloadthefilesfrom http://java.sun.com/javase/downloads/index.jsp. IfyouarerunningtheIBMJDK1.5.*,downloadthefilesfrom http://www106.ibm.com/developerworks/java/jdk/security/.

Youareusingoneofthecryptographicserviceproviders(CSPs)thatwebMethods IntegrationServerprovides(Sun,IBM,Entrust,orIAIK).Ifyouareusingadifferent provider,thelibrariessuppliedbythatprovidermustbedigitallysigned. Yourclasspathconsistsofatleastthefollowing:

webMethods_directory\common\lib\wm-isclient.jar webMethods_directory\common\lib\ext\mail.jar

IfyouwanttouseanyclassesintheEntrustToolkit,theclasspathmustcontainthe following:
webMethods_directory\common\lib\ext\enttoolkit.jar

Limitations
WhenDevelopergeneratesclientcode,itignoresinputoroutputvariablesthatareof typeObjectorObjectlist.Clientcodeisnotgeneratedforthesevariables. WhenDevelopergeneratesclientcode,Developerreplacesanyspaceinavariable namewithanunderscore. TheclientcodethatDevelopergeneratesdoesnotsupportmultipleinputoroutput variableswiththesamename. Ifyouwanttooverridetheselimitations,youwillneedtomodifytheclientcodethat Developergenerates.

webMethods Developer Users Guide Version 7.1.1

333

13 Creating Client Code

Procedure
UsethefollowingproceduretogenerateJavaclientcodethatinvokesaservice: To generate Java client code that invokes a service 1 2 3 4 5 Opentheserviceforwhichyouwanttogenerateclientcode. OntheToolsmenu,clickGenerate Code. IntheCodeGenerationdialogbox,selectFor calling this service from a client,andthen clickNext. IntheLanguagefield,selectJava,andthenclickNext. SpecifythedirectorywhereyouwantDevelopertoplacethegeneratedclientcode. Eitherselectanexistingdirectoryortypethepathforanewdirectory.Ifyoutypethe pathforanewdirectory,Developercreatesthedirectory. ClickFinish. DevelopergeneratesthefilethatcontainstheJavaclientcode(ServiceName.java)and aReadme.txtfile.TheJavaclientcodeiswrittentotheharddiskinISO8859_1,the charactersetinwhichthefileisencoded. Modifythegeneratedclientcodetomeetyoursitesneeds.Youcanupdatetheclient codetoinvokebuiltinservicesandtousetheprovidedJavaAPI.Forinformation aboutthebuiltinservicesthatareavailable,seethewebMethodsIntegrationServer BuiltInServicesReference.DocumentationfortheJavaAPIcanbefoundat Developer_directory\doc\api\Java\index.html. Tocompleteyourclientapplication,refertotheReadme.txtfilelocatedinthesame directoryasyourclientcode.

Files that Are Generated

ThissectiondescribesthefilesthatDevelopergeneratesforaJavaclientapplication. File Name Readme.txt Description AfilethatcontainsinformationandinstructionsfortheJavaclient code.Refertothisfileforinformationaboutcompilingand runningtheJavaclientapplication. Anexamplefile,encodedinISO8859_1,thatcontainsthe applicationcodefortheJavaclient.Theapplicationcodeincludes arudimentaryuserinterfacethatusestheclassesinthe FolderNamedirectory.Itisnotintendedforuseasisincustom applications.

ServiceName.java

334

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

Building a C/C++ Client

YoucanuseDevelopertogenerateC/C++clientcodethatinvokesaservice.

Assumptions
webMethodsIntegrationServerisrunning. AplatformthathastheC/C++compiler(forexample,GCC)isinstalled.webMethods generatescodeforthefollowingplatforms:Windows,Solaris,HPUX,Linux,AIX. Thewmisclient.jarfileisintheclasspathforDeveloper.Theclient.jarfileisa webMethodsfilethatislocatedinthewebMethods_directory\common\libdirectory. TheMakefacilityisinstalled. JDK1.1.xisinstalled(ifyouintendtousetheClibrariesprovidedwithIntegration ServerandDeveloper). Important! TheprovidedClibrariesarebuiltusingJDK1.1.7.Ifyouwanttousea differentversionoftheJDKtocompileC/C++services,youneedtorebuildtheC/C++ librarieswiththatJDKandthenreplacetheoldlibraryfileswiththerebuiltones.For moreinformationaboutrebuildingtheClibraries,seetheREADMEinstalledwith theC/C++SDK. TorebuildtheClibraries,youneedusetheC/C++SDK.TheC/C++SDKisnot installedbydefault.ToinstalltheC/C++SDK,selectitfromthelistofinstallable componentsduringinstallation.

Limitations
TheclientcodethatDevelopergeneratesdoesnotsupportmultipleinputoroutput variableswiththesamename. WhenDevelopergeneratesclientcode,Developerreplacesanyspaceinavariable namewithanunderscore. Ifyouwanttooverridetheselimitations,youwillneedtomodifytheclientcodethat Developergenerates.

webMethods Developer Users Guide Version 7.1.1

335

13 Creating Client Code

Procedure
UsethefollowingproceduretohaveDevelopergenerateC/C++clientcodethatinvokesa service: To generate C/C++ client code that invokes a service 1 2 3 4 5 Opentheserviceforwhichyouwanttogenerateclientcode. OntheToolsmenu,clickGenerate Code. IntheCodeGenerationdialogbox,selectFor calling this service from a client;thenclick Next. IntheLanguagefield,selecttheC/C++platformforwhichyouarecreatingclientcode. ClickNext. IdentifythedirectorywhereyouwantDevelopertoplacethegeneratedclientcode. Eitherselectanexistingdirectoryortypethepathforanewdirectory.Ifyoutypethe pathforanewdirectory,Developercreatesthedirectory. ClickFinish. DevelopergeneratesthefilethatcontainstheCclientcode(ServiceName.c),afilethat containscompilingsettings(ServiceName.mak),andaCReadme.txtfile. Modifythegeneratedclientcodetomeetyoursitesneeds.Youcanupdatetheclient codetoinvokebuiltinservicesandtousethewebMethodsCAPI.Forinformation aboutthebuiltinservicesthatareavailable,seethewebMethodsIntegrationServer BuiltInServicesReference.FordocumentationabouttheCAPI,see Developer_directory\doc\api\C\index.html. Tocompleteyourclientapplication,refertotheCReadme.txtfilelocatedinthesame directoryasyourclientcode.

Files that Are Generated

ThissectiondescribesthefilesthatDevelopergeneratesforaC/C++clientapplication. File Name CReadme.txt Description AfilethatcontainsinformationandinstructionsfortheCclient code.Refertothisfileforinformationaboutcompiling,running, anddeployingyourC/C++clientapplication. AfilethatcontainscompilingsettingsfortheC/C++client.Besure toupdatethisfilewiththecorrectsettingsforyourenvironment. AnexamplefilethatcontainstheC/C++clientcode.Itisnot intendedforuseasisincustomapplications.

ServiceName.mak ServiceName.c

336

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

Building a Visual Basic Client

YoucanuseDevelopertogenerateVisualBasicclientcodethatinvokesaservice. Developercreatesfilesthatcontainthelayoutandthecodeforyourapplication.

Assumptions
webMethodsIntegrationServerisrunning. VisualBasicVersion6isinstalled. webMethods7TypeLibraryisinstalled. Note: ThewebMethods7TypeLibraryisaCOMobjectthatVisualBasicusesto interactwithwebMethodsIntegrationServer.ThewebMethods7TypeLibraryis automaticallyinstalledwhenyouinstallDeveloper.

Environment Setup
YoursystemPATHenvironmentvariablemustincludethefollowingdirectory: webMethods7\jvm\win150\jre\bin\client

Limitations
TheclientcodethatDevelopergeneratessupportsonlyinputvaluesandoutput valuesoftypeString,Stringlist,andStringtable. TheclientcodethatDevelopergeneratesdoesnotsupportmultipleinputoroutput variableswiththesamename. WhenDevelopergeneratesclientcode,Developerreplacesanyspaceinavariable namewithanunderscore. Ifyouwanttooverridetheselimitations,youwillneedtomodifytheclientcodethat Developergenerates.

Procedure
UsethefollowingproceduretohaveDevelopergenerateVisualBasicclientcodethat invokesaservice. To generate Visual Basic client code that invokes a service 1 2 Opentheserviceforwhichyouwanttogenerateclientcode. OntheToolsmenu,clickGenerate Code.

webMethods Developer Users Guide Version 7.1.1

337

13 Creating Client Code

3 4 5

IntheCodeGenerationdialogbox,selectFor calling this service from a client,andclick Next. IntheLanguagefield,selectVisual Basic 5/6,andclickNext. IdentifythedirectorywhereyouwantDevelopertoplacethegeneratedclientcode. Eitherselectanexistingdirectoryortypethepathforanewdirectory.Ifyoutypethe pathforanewdirectory,Developercreatesthedirectory. ClickFinish. Developergeneratesseveralfiles,includingtheserviceNameReadMe.txtfile.Thisfile containsdetailedinformationaboutallthegeneratedfiles.Refertoittocomplete yourclientapplicationandforinformationaboutdeployingyourclientapplication.

Files that Are Generated

ThissectiondescribesthefilesthatDevelopergeneratesforaVisualBasicclient application.

General Files
File Name ServiceName.vbp ServiceNameReadme.txt Description TheVisualBasicprojectfile. Thefilethatcontainsinformationandinstructionsforthe VisualBasicclientcode.Refertothisfileforinformation aboutdeployingyourVisualBasicclientapplication.

Files for the User Interface

File Name frmArrayInput.frm frmOutput.frm Description Containslayoutandcodethatisusedifanyoftheinput valuesfortheserviceareoftypeStringlist. Containslayoutandcodethatisusedwhentheservice returnsoutput.ItalsocontainstheSetup,Invoke,andExit buttons. Containslayoutandcodethatpromptsfortheserver propertiesforthewebMethodsIntegrationServeron whichtheservicetoexecuteresides. Containslayoutandcodethatisusedifanyoftheinput valuesfortheserviceareoftypeString.

frmSetup.frm

frmStringInput.frm

338

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

File Name frmTableInput.frm wmSampleLib.bas

Description Containslayoutandcodethatisusedifanyoftheinput valuesfortheserviceareoftypeStringtable. Containscodethatisspecifictothesampletemplatethat Developergenerates.

Files Containing the Code that Invokes the Service

File Name ServiceName.bas Description Anexamplefilethatillustrateshowtousetheserviceclass inanapplication.Thismoduleisdependentonobjectsin theprojecttemplatethatDeveloperprovides.Itisnot intendedforuseasisincustomapplications. Theserviceobject.Youincludethisobjectinyourown project.

ServiceName.cls

File Containing the Code that Interacts with webMethods Integration Server
File Name wmVBConnection.bas Description Codeusedasalayerofabstractiontointeractwith webMethodsIntegrationServer.

Building an Excel Client

YoucanuseDevelopertogenerateclientcodethatexecutesaservicefromaMSExcel spreadsheet.

Assumptions
webMethodsIntegrationServerisrunning. Excel97orExcel2000isinstalled. webMethods7TypeLibraryisinstalled. Note: ThewebMethods7TypeLibraryisaCOMobjectthatVisualBasicusesto interactwithwebMethodsIntegrationServer.ThewebMethods7TypeLibraryis automaticallyinstalledwhenyouinstallDeveloper.

webMethods Developer Users Guide Version 7.1.1

339

13 Creating Client Code

Limitations
TheclientcodethatDevelopergeneratesonlysupportsinputvaluesoftypeString andoutputvaluesoftypeString,Stringlist,andStringtable. TheclientcodethatDevelopergeneratesdoesnotsupportmultipleinputoroutput variableswiththesamename. WhenDevelopergeneratesclientcode,Developerreplacesanyspaceinavariable namewithanunderscore. Ifyouwanttooverridetheselimitations,youwillneedtomodifytheclientcodethat Developergenerates.

Procedure
UsethefollowingproceduretohaveDevelopergenerateExcelclientcodethatinvokesa service. To generate Excel client code that invokes a service 1 2 3 4 5 Opentheserviceforwhichyouwanttogenerateclientcode. OntheToolsmenu,clickGenerate Code. IntheCodeGenerationdialogbox,selectFor calling this service from a client,andclick Next. IntheLanguagefield,selectExcel 97/2000,andclickNext. IdentifythedirectorywhereyouwantDevelopertoplacethegeneratedclientcode. Eitherselectanexistingdirectoryortypethepathforanewdirectory.Ifyoutypethe pathforanewdirectory,Developercreatesthedirectory. ClickFinish. Developergeneratesseveralfiles,includingtheserviceNameReadMe.txtfile.Thisfile containsdetailedinformationaboutallgeneratedfiles. 7 CopythewmXLTemplate.xlsfilethatDeveloperprovidestothedirectorythat containstheclientcodethatDevelopergenerated.ThewmXLTemplate.xlsfileis locatedintheDeveloper_directory\support\Exceldirectory. OpenthewmXLTemplate.xlsfile.Whenpromptedtoindicatewhetheryouwantto enablemacros,selectEnable Macros. FollowtheinstructionsinthewmXLTemplate.xlsfiletocompleteyourclient application.SeetheServiceNameReadMe.txtfileforinformationaboutdeployingyour clientapplication.

8 9

340

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

Files that Are Generated

ThissectiondescribesthefilesthatDevelopergeneratesforanExcelclientapplication. File Name ServiceNameReadMe.txt Description Afilethatcontainsinformationandinstructionsforthe VisualBasicclientcode.Refertothisfileforinformation aboutdeployingyourVisualBasicclientapplication. Anexamplefilethatillustrateshowtousetheserviceclass inaspreadsheet.Thismoduleisdependentonobjectsin theprojecttemplatethatDeveloperprovides.Itisnot intendedforuseasisincustomapplications. Theserviceobject.Youincludethisobjectintoyourown project.

ServiceName.bas

ServiceName.cls

Building a Browser-Based Client

YoucaninvokeaservicewithaURL.Thismeansthatyoucaninvokeaserviceby enteringtheURLintoyourWebbrowserorbyembeddingtheURLinWebpages. Tobuildabrowserbasedclient,createoneormoreWebpagesthatinvokeURLsforone ormoreservices.WhenwebMethodsIntegrationServerreceivesthefirstURLfroma Webbrowser,itcreatesasessionfortheclientonwebMethodsIntegrationServer.The sessioninformationisstoredinacookieinthebrowser.Astheuserofthebrowserbased applicationclicksonlinkstoURLsthatinvokeservices,webMethodsIntegrationServer usesthecookiestofindsessioninformationfortheclient.webMethodsIntegrationServer keepsthesessioninformationfortheclientuntilthesessionexpires.Sessionsexpire basedontheconfiguredsessiontimeoutvalue.Formoreinformationaboutsettingthe sessiontimeoutlimit,refertothewebMethodsIntegrationServerAdministratorsGuide. Note: YoucannotuseDevelopertogeneratebrowserbasedclients.

Assumptions
webMethodsIntegrationServerisrunning. Theinputvaluesfortheservicesyouwanttoinvokearedetermined.Youwillneedto includetheinputvaluesintheURLthatyouusetoinvokeaservice.

Limitations
WhenyoutestaserviceusingtheRun in Browsercommand,onlyinputvaluesofthetype StringandStringlistwillbepassedtotheservice.Inputvaluesofthetypedocument, documentlist,Object,andObjectlistwillnotbedisplayedwhentheWebpageisserved.

webMethods Developer Users Guide Version 7.1.1

341

13 Creating Client Code

Invoking Services with a URL

First,buildyourWebpagesusinganytoolyouchoose.ToinvoketheURL,useeitherthe HTTPGETorthePOSTmethod.Ineithercase,useaURLsimilartothefollowing:
1 2 3 4 5

http://IS_server:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1

Item
1 2 3

Description IdentifiesthewebMethodsIntegrationServeronwhichtheserviceyouwant toinvokeresides. Specifiestherequiredkeywordinvoke,whichtellswebMethods IntegrationServerthattheURLidentifiesaservicethatistobeinvoked. Identifiesthefolderinwhichtheservicetoinvokeresides.Separate subfolderswithperiods.Thisfieldiscasesensitive.Besuretousethesame combinationofupperandlowercaselettersasspecifiedinthefoldername onwebMethodsIntegrationServer. Identifiestheservicethatyouwanttoinvoke.Thisfieldiscasesensitive.Be suretousethesamecombinationofupperandlowercaselettersasspecified intheservicenameonwebMethodsIntegrationServer. Specifiestheinputvaluesfortheservice.Specifyaquestionmark(?)before theinputvalues.Thequestionmarksignalsthebeginningofinputvalues. Eachinputvalueisrepresentedasvariable=value.Thevariableportioniscase sensitive.Besuretousethesamecombinationofupperandlowercaseletters asspecifiedinyourservice.Ifyourservicerequiresmorethanoneinput value,separateeachvariable=valuewithanampersand(&). Note: OnlyspecifythispartoftheURLwhenusingtheHTTPGETmethod.

Note: IfyouareservingtheWebpagesthatinvokeservicesfromawebMethods IntegrationServer,youcanusearelativeURLtoinvoketheservice.Bydoingso,you canservetheexactWebpagefromseveralserverswithouthavingtoupdatethe URLs.

Using the HTTP GET Method

TousetheGETmethod,embedaURLthatincludesalltheinputvaluesfortheservicein thequerystringportionoftheURL.WhentheserverreceivestheURL,ittranslatesthe inputvaluesintoanIDataobject.Formoreinformationabouthowtheservercreatesthe IDataobjectthatitsendstotheservice,refertoInputtotheServiceonpage 343.

342

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

Using the HTTP POST Method

TousethePOSTmethod,createanHTMLforminyourWebpage.Createfieldsinthe HTMLforminwhichauserwillsupplytheinputinformation.Thevaluesyouspecifyfor theNAMEattributesoftheHTMLformfieldsshouldmatchthenamesofinputvalues thattheserviceexpects.Besuretousetheexactcombinationofupperandlowercase lettersasspecifiedinyourservice.Forexample,ifyourservicerequirestheinputvalues skuandquantity,youmightcreateanHTMLformwiththefollowingfields:
<SELECT NAME="sku"> <OPTION VALUE="A1">A1</OPTION> <OPTION VALUE="B2">B2</OPTION> <OPTION VALUE="C3">C3</OPTION> </SELECT> <INPUT TYPE="TEXT" NAME="quantity" VALUE="1">

SpecifytheURLfortheserviceintheACTIONattributeandPOSTintheMETHODattribute. Forexample:
<FORM ACTION="/invoke/sample.webPageDemo/getProductCost" METHOD="POST">

Aftertheuserfillsintheformandsubmitsit,theWebbrowsercreatesadocumentthat containstheinformationtheusersuppliedintheHTMLform(performsanHTTPPOST). ThebrowserinvokestheURLidentifiedintheACTIONattribute,whichinvokesthe serviceonwebMethodsIntegrationServer,andthebrowserpoststhedocumentthat containstheusersinputinformationtowebMethodsIntegrationServer.Formore informationabouthowtheservercreatestheIDataobjectthatitsendstotheservice,see InputtotheServiceonpage 343.

Input to the Service

RegardlessofwhetherwebMethodsIntegrationServerreceivesaURLthatusesthe HTTPGETorPOSTmethod,itcreatesanIDataobjectfromtheinputinformation.Itthen passestheIDataobjecttothespecifiedservice.Thisbecomesthepipelineuponwhichthe serviceoperates. Tocreatethepipelineobject,webMethodsIntegrationServercreatestwokey/valuepairs foreachinputvalue:oneoftypeStringandoneoftypeStringlist.Forexample,ifthe inputvaluescontainthevariableskuwithvalueA1andquantitywithvalue1,theservice ispassedthefollowingIDataobject: Key sku skuList quantity quantityList Value A1 A1 1 1 Data Type String Stringlist String Stringlist

webMethods Developer Users Guide Version 7.1.1

343

13 Creating Client Code

Note: AvoidusinginputvariablenamesthatendinList.AlthoughtheIntegration ServerwillacceptvariablenamesendinginList,theresultingIDatamaynotbe structuredinthewayyouneed.Forexample,ifyouweretopassinavariablecalled skuList,theresultingIDatawillcontainaStringcalledskuListandaStringlist calledskuListList.Moreover,ifyouweretopassinvariablesnamedskuand skuList,subsequentskuandskuListvariablesinthequerystringmaynotbe placedintheIDatafieldsasexpected. IfyoumustuseListattheendofyourvariablename,considerusinglist (lowercase)orappendingoneormorecharactersattheendofthename(forexample, abcListXX). Whentheserverreceivesmultipleinputvaluesthatareassociatedwiththesamevariable name,theStringvariableintheIDataobjectcontainsonlythevalueofthefirstvariable; theStringlistvariablecontainsallvalues.Forexample,thefollowingshowsaURLthat containstwovaluesforthevariableyearandtheresultingIDataobjectthattheserver creates:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999

Key year yearList

Value 1998 1998 1999

Data Type String Stringlist

Similarly,iftheHTMLformcontainstwofieldswiththesamenameandausersupplies valuesformorethanone,theStringvariableintheIDataobjectcontainsonlythevalueof thefirstvariable;theStringlistvariablecontainsallvalues.Forexample,thefollowing showssampleHTMLcodethatrenderscheckboxes:

<INPUT TYPE="checkbox" NAME="Color" VALUE="blue">Blue<BR> <INPUT TYPE="checkbox" NAME="Color" VALUE="green">Green<BR> <INPUT TYPE="checkbox" NAME="Color" VALUE="red">Red<BR>

Ifthebrowseruserselectsallcheckboxes,thedocumentthatispostedtowebMethods IntegrationServerwillcontainthreevaluesforthevariablenamedColor.Thefollowing showstheIDataobjectthattheserverpassestotheservice: Key Color ColorList Value blue blue green red Data Type String Stringlist

344

webMethods Developer Users Guide Version 7.1.1

13 Creating Client Code

Output from the Service

Bydefault,webMethodsIntegrationServerdisplaystheoutputfromaserviceinaHTML Webpage,usingatabletorendertheoutputvalues.However,youcanformattheoutput usingoutputtemplates.Youcanuseanoutputtemplatethatformatstheoutputfromone serviceandincludesaURLthatinvokesanotherservice.Formoreinformationabout outputtemplates,seeAssigninganOutputTemplatetoaServiceonpage 127.

webMethods Developer Users Guide Version 7.1.1

345

13 Creating Client Code

346

webMethods Developer Users Guide Version 7.1.1

14

Subscribing to Events
348 350 357 359 360 362 364 366 367 368 370 372

The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

347

14 Subscribing to Events

The Event Manager

TheEventManagermonitorstheserverforeventsandinvokeseventhandlerswhenthose eventsoccur.AneventisaspecificactionthattheEventManagerrecognizesandan eventhandlercanreactto.Aneventhandlerisaservicethatyouwritetoperformsome actionwhenaparticulareventoccurs. Currently,theEventManagerrecognizesthefollowingtypesofevents: Event Type Alarm Description OccurswhenIntegrationServerthrowsanexceptionregardingthe statusorhealthoftheserver.Theservergeneratesalarmevents whenausercannotlogontotheserver,aportcannotbestarted,a userisdeniedaccesstoaport,anerroroccursinClusterManager, oraservicecannotexecutebecauseoferrors.Subscribetoalarm eventstoinvokeeventhandlersthatperformspecificactionssuchas notifyingadministratorsaboutportaccessexceptionsandservice failures,orsendinginformationtoaconsolewhenaportcannotbe started. Occurswhenaservicegeneratesauditdata.Subscribetoaudit eventstoinvokespecificactionswhenaparticularserviceorclassof serviceexecutes. Occurseverytimeaservicethrowsanexception.Subscribeto exceptioneventstoinvokespecificeventhandlerswhenaparticular serviceorclassofservicefails. Occurswhenaclientusesguaranteeddeliverytoinvokeaservice onanIntegrationServerandwhentheserverreturnstheservice resultstotherequestingclient.Therearetwotypesofguaranteed deliveryevents:GDStartandGDEnd.SubscribetoGDStartand GDEndeventstoinvokeeventhandlersthatperformactionssuch asloggingguaranteeddeliverytransactionstoafileorsending notification. OccurswhenthecontentsofaJMSmessagesentfromtheclientside queuecausetheJMSprovidertothrowanontransienterror. SubscribetoJMSdeliveryfailureeventstocaptureinformation aboutJMSmessagesthattheJMSproviderdidnotprocess successfully.Forexample,youmightwanttousetheeventhandler tosendnotificationorloginformationabouttheundeliveredJMS message. OccurswhenaJMStriggerserviceendsbecauseofanontransient ortransienterrorandIntegrationServerisconfiguredtogenerate JMSretrievalfailureevents.SubscribetoJMSretrievalfailureevents toinvokeeventhandlerswhenJMSmessageprocessingendsin error.

Audit

Exception

Guaranteed Delivery

JMS Delivery Failure

JMS Retrieval Failure

348

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Event Type Port Status

Description OccurseachtimeIntegrationServerupdatestheserverstatistics. Theportstatuseventprovidesinformationaboutthestatusofall theportsconfiguredonIntegrationServer.Subscribetoportstatus eventstoinvokeeventhandlersthatperformactionssuchas sendingportstatusdatatoanetworkmonitoringsystemorwriting portstatusdatatoalogfile. Occurswhenthepub.replicator:generateReplicationEventserviceexecutes. Subscribetoreplicationeventstoinvokeeventhandlersthat performactionssuchasnotifyingpackagesubscriberswhena packageispublishedandmaintainingalogofpulledordistributed packages. Occurswhenanadministrativeoroperationalsecurityactiontakes placeonIntegrationServerandthatsecurityactionisconfiguredfor auditing. Administrativeactionsrefertoconfigurationchangesrelatedto IntegrationServersecurityactivities.Examplesofsecurityactions include:modificationtoauthorization,authentication,portsettings, auditsettings,SSLconfiguration,passwordlengths,androot certificates. Operationalactionsrefertosuccessfulandunsuccessfullogin attemptstoIntegrationServer,andsuccessfulorunsuccessfulaccess toIntegrationServerservices,documents,andportlets.

Replication

Security

Session

OccurswhenaclientstartsorendsasessionontheIntegration ServerorwhentheIntegrationServerterminatesaninactive session.Therearethreetypesofsessionevents:sessionstart,session end,andsessionexpire.Subscribetosessioneventstoinvokeevent handlersthatperformactionssuchasmaintainingyourownlog files. OccureachtimeIntegrationServerupdatesthestatisticslog (stats.log).Subscribetostateventstoinvokeeventhandlersthat performactionssuchasmaintainingyourownlogfileorsending serverstatisticstoanetworkmonitoringsystem. OccurwhenanIntegrationServerbeginsandfinishesprocessinga guaranteeddeliverytransaction.Therearetwotypesoftransaction events:TxStartandTxEnd.Subscribetotransactioneventsto invokeeventhandlersthatperformspecificactions(suchassending notificationorlogginginformation)whenaparticularguaranteed deliverytransactionbeginsorfinishesprocessing.

Stat events

Transaction events

webMethods Developer Users Guide Version 7.1.1

349

14 Subscribing to Events

What Are Event Handlers?

Aneventhandlerisaservicethatyouwritetoperformsomeactionwhenaparticular eventoccurs.(Aneventhandlercanbeanytypeofservice,suchasaflowserviceora Javaservice.)Eventhandlerssubscribetotheeventsthattheywanttobenotifiedof.For example,ifyouwantedaneventhandlertoexecutewhenaparticularservicethrowsan exception,yousubscribetheeventhandlertotheexceptioneventforthatservice.

What Happens When an Event Occurs?

Whenaneventoccurs,theEventManagerautomaticallyinvokesalleventhandlersthat subscribetotheevent.Theeventhandlersreceiveaninputobjectcontainingruntime information.Theexactcontentofthisinputobjectvariesdependingonthetypeofevent thatoccurredand,forauditevents,theruntimepropertiessetonbothIntegrationServer andtheservicethatgeneratedtheevent. Onceaneventhandlerisinvoked,itsexecutioniscompletelyasynchronousoftheevent thatinvokedit.Iftheexecutionofaserviceinvokesaneventhandler(aswithauditand exceptionevents),theexecutionpathoftheinvokingserviceisnotblockedoralteredin anyway(infact,itisneverevenawarethatitinvokedaneventhandler). Otherpointstokeepinmindabouteventsandeventhandlers: Aneventcanhavemorethanonesubscriber,whichmeansthatasingleeventmight invokeseveraleventhandlers. Ifaneventinvokesmorethanoneeventhandler,alltheeventhandlersexecute simultaneously.Theydonotexecuteseriallyandtheyarenotinvokedinany particularorder.(Ifyouhaveaseriesofactionsthatmustexecuteinaspecific sequence,youshouldencapsulatetheentiresequencewithinasingleeventhandler.) Aneventhandlercansubscribetomorethanoneevent. Wheneventhandlersrun,theydonotgenerateauditevents. Ifaneventhandlerthrowsanexception,itgeneratesanexceptionevent.Thisistrue foralleventhandlersbutexceptioneventhandlers.Whenanexceptioneventhandler throwsanexception,itdoesnotgenerateanexceptionevent.

Managing Event Subscriptions

YoucanusetheEventManagerinDevelopertomanageallofyoureventsubscriptions. TheEventManagercanperformthefollowingtasks: Subscribeeventhandlerstoevents. Vieworediteventsubscriptions. Suspendeventsubscriptions. Deleteeventsubscriptions.

350

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Thefollowingsectionscontainmoreinformationabouteachofthesetasks. Note: Youcanalsousebuiltinservicestoadd,modify,anddeleteeventsubscriptions. Theseservicesarelocatedinthepub.eventfolder.Formoreinformationaboutbuiltin services,seethewebMethodsIntegrationServerBuiltInServicesReference.

Subscribing to an Event
YoucanusetheEventManagerinDevelopertosubscribetoaneventonthecurrent server.ThisactionregisterstheeventhandlerwiththeEventManagerandspecifies whicheventswillinvokeit.ToaccesstheEventManager,usetheToolsEvent Manager command. Use the Event Manager in Developer to subscribe to events
To subscribe to an event, specify the type of event that you want to react to... ...a filter to select the specific events you want to react to... ...and the name of the event handler that is to be executed when this event occurs.

Usethefollowingproceduretosubscribetoaneventonthecurrentserver.Toperform thisprocedure,youmusthavealready: Identifiedtheeventtypeyouwanttosubscribeto Identifiedtheserviceorservicesthatgenerateaneventyouwanttosubscribeto(if youwanttosubscribetoanauditevent,exceptionevent,orGDStartevent) Writtentheeventhandlerthatwillexecutewhentheidentifiedeventoccurs To subscribe to an event on the current server 1 2 3 OntheToolsmenu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selecttheevent typetowhichyouwanttosubscribe. Click toaddanewsubscriber.

webMethods Developer Users Guide Version 7.1.1

351

14 Subscribing to Events

IntheEnterInputValuesdialogbox,completethefollowingfields: In this field... Specify... Service Thefullyqualifiednameoftheeventhandlerthatwillsubscribetothe event(thatis,theservicethatwillexecutewhentheeventoccurs).You caneithertypethenameintheServicefieldorclick tolocateand selecttheservicefromalist. Example: sgxorders.Authorization:LogAuthTrans Filter Apatternstringtofurtherlimittheeventsthiseventhandlersubscribes to.Filtersvarydependingontheeventtypeyouaresubscribingto. Forexample,ifyouaresubscribingtoanauditorexceptionevent, createafiltertospecifythenamesofserviceswhoseeventsthisevent handlersubscribesto(thatis,theservicesthat,whenexecuted,will invoketheeventhandlerspecifiedinService). Youcanusethe*characterasawildcard(thisistheonlywildcard characterrecognizedbythispatternstring).Thepatternstringiscase sensitive. Formoreinformationaboutcreatingeventfilters,seeCreatingEvent Filtersonpage 352. Comment Enabled Anoptionaldescriptivecommentaboutthissubscription. Whetherthesubscriptionisactiveorinactive.Settotruetoactivatethe subscription.Settofalsetodeactivatethesubscription.(Thisallowsyou totemporarilysuspendasubscriptionwithoutdeletingit.)

ClickOK.Subscriptionstakeeffectimmediately. Note: IntegrationServersavesinformationforeventtypesandeventsubscriptionsin theeventcfg.binfile.ThisfileisgeneratedthefirsttimeyoustarttheIntegration Serverandislocatedinthefollowingdirectory:IntegrationServer_directory\config. CopythisfilefromoneIntegrationServertoanothertoduplicateeventsubscriptions acrossservers.

Creating Event Filters

Eventfiltersallowyoutobeveryselectiveaboutwhicheventsyousubscribeto.Event filterslimittheeventsforaneventtypethatinvokeaneventhandler.Byusingevent filters,youcansubscribeaneventhandlertoonlythoseeventsgeneratedbyaparticular service,package,user,orport.Forexample,youmightwantaneventhandlertobe invokedonlywhenaspecificservicegeneratesanauditevent.Or,youmightwantan eventhandlertobeinvokedonlywhenaspecificuserlogsontotheIntegrationServer.

352

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Thefollowingtableidentifiestheinformationthatyoucanfilteronforeacheventtype. Noticethatyoucannotcreateafilterforsomeeventtypes.Fortheseeventtypes,every generatedeventinvokestheeventhandlerssubscribedtoit. Important! Theasterisk(*)istheonlywildcardcharacterallowedinaneventfilter.All othercharactersinthepatternstringaretreatedasliterals.Patternstringsarecase sensitive. For this event type... Alarm Event You create a filter for... Themessagegeneratedbythealarmevent.Createafilterthat specifiessomeofthetextofthemessage.Theeventhandlerwith thisfilterwillprocessallalarmeventscontainingthespecified text. Thefollowingfilterspecifiesthatanyalarmeventsthatgeneratea messagecontainingthewordportwillinvoketheevent handler:
*port*

Audit Event

Thefullyqualifiednameoftheservicethatgeneratestheaudit event.Createafiltertospecifytheserviceswhoseauditevents youwanttoinvoketheeventhandler. Thefollowingfilterspecifiesthattheservice sgxorders.Authorization:creditAuthwillinvoketheeventhandler:

sgxorders.Authorization:creditAuth

Exception Event

Thefullyqualifiednameoftheservicethatgeneratesthe exceptionevent.Createafiltertospecifytheserviceswhose exceptioneventsyouwanttoinvoketheeventhandler. Thefollowingfilterspecifiesthatallservicesthatstartwiththe wordcreditandbelongtoanyfolderwillinvoketheevent handler:

*:credit*

GD End Event

N/A ThefilterforallGDEndeventsisthefollowing:
*

GD Start Event

Thefullyqualifiednameoftheservicethatisbeinginvokedusing guaranteeddelivery.Createafiltertospecifytheservicesthat, wheninvokedusingguaranteeddelivery,willinvoketheevent handler. Thefollowingpatternstringspecifiesthatallservicesthatstart withthewordsendPOandbelongtoanyfolderwillinvokethe eventhandler:

*:sendPO*

webMethods Developer Users Guide Version 7.1.1

353

14 Subscribing to Events

For this event type... JMS Delivery Failure Event

You create a filter for... ThenameoftheJMSconnectionaliasusedtosendthemessageto theJMSprovider. ThefollowingfilterspecifiesthataJMSdeliveryfailureevent involvingaJMSconnectionaliaswithXAintheJMSconnection aliasnamewillinvoketheeventhandler:

*XA*

JMS Retrieval Failure Event

ThefullyqualifiednameoftheJMStriggerthatcalledthetrigger serviceforwhichtheerroroccurred. ThefollowingfilterspecifiesthataJMSretrievalfailureevent involvingaJMStriggernamedordering:processTransactionwill invoketheeventhandler:

*ordering:processTransaction*

Port Status Event

N/A Thefilterforallportstatuseventsisthefollowing:
*

Replication Event

Thenameofthepackagebeingreplicated.Createafiltertospecify thepackagesthat,whenreplicated,willinvoketheeventhandler. Thefollowingfilterspecifiesthatareplicationeventinvolvingthe packagenamedAcmePartnerPkgwillinvoketheeventhandler:

AcmePartnerPkg

Security Event Session End Event

N/A Youcannotfilteronsecurityevents. N/A Thefilterforallsessionendeventsisthefollowing:

*

Session Expire Event

N/A Thefilterforallsessionexpireeventsisthefollowing:
*

Session Start Event

TheusernamefortheuserstartingthesessionontheIntegration Serverorthegroupstowhichtheuserbelongs.Createafilterto specifywhichusersorwhichusergroupsinvokeaneventhandler whentheystartasessionontheserver. Thefollowingfilterspecifiesthatasessionstarteventgenerated byauserintheAdministratorsgroupwillinvoketheevent handler.

*Administrators*

354

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

For this event type... Stat Event

You create a filter for... N/A Thefilterforallstateventsisthefollowing:

*

Tx End Event

N/A ThefilterforallTxEndeventsisthefollowing:
*

Tx Start Event

N/A ThefilterforallTxStarteventsisthefollowing:
*

Creating Event Filters for Services

Whenyoucreateafilterforaservicename,youcanbeveryselectiveaboutwhich serviceseventsyousubscribeto.Youcanuseregularexpressionstocreateeventfilters forservicenames.Thefollowingexamplesshowwaysyoucanuseregularexpressionsas eventfilterstospecifyaneventthataparticularservicegenerates. This filter...
sgxorders.Auth:creditAuth sgxorders.Auth:credit*

Will select events generated by... Theservicesgxorders.Auth:creditAuth. Allservicesinthesgxorders.Auth folder,startingwiththe characterscredit. Allservicesinthesgxorders.Auth folder. Allservicesinthesgxorders folderanditssubfolders. Allservicesstartingwiththecharacterscreditthat resideinanysubfolderwhosenamestartsthe charactersAuth. Allservicesstartingwiththecharacterscreditinany folder. Allservices.

sgxorders.Auth:* sgxorders.* *.Auth*:credit*

*:credit*

Viewing and Editing Event Subscriptions

To view or edit an event subscription on the current server 1 2 OntheToolsmenu,clickEvent Manager. IntheView event subscribers forlist,selecttheeventtypeforwhichyouwanttoview subscriptions.

webMethods Developer Users Guide Version 7.1.1

355

14 Subscribing to Events

3 4 5 6

Clickthesubscriptionyouwanttoedit,andthenclick

ModifythefieldsintheEnterInputValuesdialogboxasneededandthenclickOK. Repeatsteps 24foreachsubscriptionyouwanttovieworedit. ClickOKwhenyoufinishviewingoreditingeventsubscriptions.Yourchangestake effectimmediately.

Suspending Event Subscriptions

Youcansuspendaneventsubscription.Bysuspendinganeventsubscription,you temporarilystoptheexecutionoftheeventhandlerwithoutdeletingorremovingthe eventhandler.Whiletheeventsubscriptionissuspended,theEventManagerdoesnot invoketheassociatedeventhandlerwhentheservergeneratestheeventtowhichitis subscribed.Youcanresumeaneventsubscriptionatanytime. To suspend an event subscription 1 2 3 4 5 6 OntheToolsmenu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selecttheevent typeforwhichyouwanttosuspendasubscription. Clickthesubscriptionyouwanttoedit,andthenclick .

IntheEnterInputValuesdialogbox,intheEnabledlist,selectfalse. Repeatsteps 24foreacheventsubscriptionyouwanttosuspend. ClickOKwhenyoufinishsuspendingeventsubscriptions.Yourchangestakeeffect immediately.

Deleting an Event Subscription

To delete an event subscription 1 2 3 4 5 OntheToolsmenu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selecttheevent typeforwhichyouwanttodeleteasubscription. Clickthesubscriptionyouwanttodelete,andthenclick .

Repeatsteps 2and3foreachsubscriptionyouwanttodelete. ClickOKwhenyoufinishdeletingevents.Yourchangestakeeffectimmediately.

356

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building an Event Handler

Buildinganeventhandlerinvolvesthefollowingbasicstages:
Stage 1 Stage 2

Creating an empty service. Duringthisstage,youcreatetheemptyservicethat youwanttouseasaneventhandler. Declaring the input and output. Duringthisstage,youdeclaretheinputand outputparametersfortheeventhandlerbyselectingthespecificationorIS documenttypefortheeventtypeinpub.event.ThespecificationandIS documenttypeindicatetheruntimedatathatwillbecontainedintheIData objectpassedtotheeventhandler. Inserting logic, code, or services. Duringthisstage,youinsertthelogic,code,or servicestoperformtheactionyouwanttheeventhandlertotakewhenthe eventoccurs.Ifyouarebuildingaflowservice,makesuretolinkdata betweenservicesandthepipeline. Testing and debugging the service. Duringthisstage,youusethetestingand debuggingtoolsavailableinDevelopertomakesuretheeventhandler worksproperly. Subscribing to the event. Duringthisstage,youusetheEventManagerto subscribetheeventhandlertotheevent.Thisactionregisterstheevent handlerwiththeEventManagerandspecifieswhicheventswillinvokeit. Youcancreatefilterstobemoreselectiveaboutwhicheventsyousubscribe to.

Stage 3

Stage 4

Stage 5

Sample Event Handler

FollowingareinstructionsforbuildinganeventhandlernamedprocessLogon.The processLogoneventhandlersendsanotificationtoaspecifiedemailaddress(suchasthe ServerAdministrator)whenanyoneintheAdministratorsgrouplogsintothe IntegrationServer.
Stage 1

To create the event handler

CreateanemptyflowserviceandnameitprocessLogon.
Stage 2

To assign input and output parameters to the event handler .

1 2 3

Onthe Input/Outputtab,nexttotheSpecification Referencefield,click ClickOK.

IntheSelectdialogbox,navigatetoandselectthepub.event:sessionStartspecification.

webMethods Developer Users Guide Version 7.1.1

357

14 Subscribing to Events

Stage 3

To insert services into the event handler andselectBrowse.

1 2 3

Ontheeditortoolbar,click

IntheBrowsedialogbox,navigatetoandselectthepub.client:smtpservice.ClickOK. OnthePipeline tab,usetheSet Value variablesinService In: For this field to subject Specify Theemailaddressforthepersontosendeventnotificationto.
%userid% logged in

modifiertoassignvaluestothefollowing

ThesubjectoftheemailmessagewillcontaintheuserIDofthe personwhologgedontotheIntegrationServerasamemberofthe Administratorsgroup. mailhost body Thenetworknameofyourmailhost(forexample, [email protected]).

Administrators user %userid% logged into session %sessionName% with session ID %ssnid%

Thebodyoftheemailmessagewillcontaintheusername,session name,andsessionIDforthepersonwhologgedontothe IntegrationServerasanAdministrator. 4 OntheFilemenu,clickSavetosavetheservice. To test and debug the event handler

Stage 4

UsethetestinganddebuggingtoolsinDeveloper(suchasTestRun)totestand debugtheservice.Formoreinformationaboutthesetools,seeChapter 11,Testing andDebuggingServices.

Stage 5

To subscribe the event handler to the event

1 2 3

OntheTools menu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selectSession Start Event. Click toaddaneweventsubscription.

358

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

IntheEnterInputValuesdialogbox,completethefollowingfields: In this field Service Filter Do this Click andusetheSelectdialogboxtonavigatetoandselectthe processLogonservice. Type: *Administrators* ThispatternstringspecifiesthattheprocessLogoneventhandlerwill executeonlywhenauserbelongingtoausergroupcontainingthe stringAdministratorslogsontotheserver. Formoreinformation,seeBuildingHandlersforSessionStart Eventsonpage 369. Comment Enabled Specifyadescriptivecommentaboutthissubscription. Selecttruetoactivatethesubscription.

ClickOK.Subscriptionstakeeffectimmediately.

Working with Alarm Events

AnalarmeventoccurswhentheIntegrationServergeneratesamessagerelatedtothe statusoftheserver.Analarmeventcanbegeneratedforthefollowingreasons: AclientexperiencesalogonfailureorisdeniedaccesstotheIntegrationServer.A clientcannotlogonbecauseofinvalidcredentials. ErrorsoccurintheClusterManager.Theinabilitytoaddaporttoaclustercancause errorsinClusterManager. Ausertriestoaccessaportandisdeniedaccesstotheport.(Thiscanhappenwhena usertriestoexecuteaservicenotallowedontheport.)Thistypeofalarmeventis sometimescalledaportaccessexception. Aportcannotbestarted.Themostcommonreasonaportcannotstartisthattheport isbeingaccessedbyanotherapplication. Aservicecannotbeloadedorexecutedduetosetuperrors.Foraflowservice,a possibleerrorisamissingXMLmetafile.ForaJavaservice,possibleerrorsincludea missingclassfileormethod. Youcanusealarmeventstoinvokeeventhandlersthatexecutewhentheserver generatesmessagesrelatedtothestatusoftheserver.Forexample,youmightwantto createaneventhandlerthatnotifiestheadministratorwhenauserisdeniedaccesstothe serverortoaport,whenaservicefailstoloadorexecute,orwhenaportdoesnotstart. Youcanalsocreateeventhandlerstosenddatatoanetworkmonitoringsystem.

webMethods Developer Users Guide Version 7.1.1

359

14 Subscribing to Events

Building Handlers for Alarm Events

WhentheEventManagerinvokesaneventhandlerforanalarmevent,theeventhandler receivesanIDataobjectcontainingthefollowingruntimedata.(AspecificationandIS documenttypefortheseparametersareprovidedinthepub.eventfolder.) Key time service Description AStringcontainingthedateandtimethatthealarmeventoccurred,inthe formatyyyy/MM/dd HH:mm:ss.SS AStringcontainingthefullyqualifiednameoftheservicethatgenerated theevent.Aservicecangenerateanalarmeventwhenaclientinvokesa servicethataccessesinformationoraserviceonaremoteserver.Ifthe clientisnotamemberofanallowedgroupfortheportontheremote server,theservicewillgenerateanalarmevent. AStringcontainingtheidentificationnumberforthesessionduringwhich thealarmeventwasgenerated.Somealarmeventsarenotgenerated duringsessions.Inthesecases,thesessionIDvariablewillnotcontaina value. AStringcontainingtheerrormessagefromthealarmevent.

sessionID

msg

Tip! Whenyousubscribeaneventhandlertoanalarmevent,youcancreateafilterfor themsgfieldtobemoreselectiveaboutthealarmeventsthatinvoketheevent handler.

Working with Audit Events

Anauditeventoccurswhenaservicegeneratesauditdata.Youcanusetheoptionsina servicesAuditpropertiestospecifywhenaservicegeneratesauditdata.Aservicecan generateauditdataonce,twice,orzerotimesduringexecution.Youcanuseauditevents toinvokeotherserviceswhenaparticularserviceexecutes.Forexample,youmightwant anauditeventgeneratedforacriticalservicetoinvokealoggingserviceoranotification service.Formoreinformationaboutspecifyingwhenaservicegeneratesauditdata,see ConfiguringServiceAuditingonpage 140.

360

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building Handlers for Audit Events

WhentheEventManagerinvokesaneventhandlerforanauditevent,theeventhandler receivesanIDataobjectthatcontainsthefollowingruntimedata.(Aspecificationandan ISdocumenttypefortheinputdataareprovidedinthepub.eventfolder.) Key time Description AStringcontainingthedateandtimetheeventoccurred.Bydefault,the formatisyyyyMMddHH:mm:ssz.Youcansettheformatbyspecifying thewatt.server.dateStampFmtproperty.Forinstructionsabouthowto specifyserverpropertysettings,seethewebMethodsIntegrationServer AdministratorsGuide. AStringcontainingthehashidentifyingtheserverthreadthatgeneratedthe auditevent. AStringcontainingthefullyqualifiednameoftheservicethatgenerated theevent. AStringcontainingtheidentificationnumberforthesessionoftheservice thatgeneratedtheevent. AStringindicatingtheauditpoint.Willbeoneofthefollowing: String
Started Ended

threadID service ssnid result

Description Thiseventmarksthebeginningofaservice. Thiseventmarkstheendofaservicethatexecuted successfully. Thiseventmarkstheendofaservicethatexecuted unsuccessfully(thatis,threwanexception)andisnot configuredtoretryorhasexhaustedallretries. Note: Tocapturedetailsaboutanyexceptionthatisthrown whenaservicefails,youmustsubscribetoExceptionEvents. ForinformationaboutExceptionEvents,seethefollowing section.

Failed

Retried

Aretriedeventwillbecreatedeachtimeaserviceisretried. Eventsareonlycreatedforaserviceifauditingforthattypeof eventisenabledfortheservice(forexample,starteventswill notbecreatedunlessauditingforservicestartisenabledfor thatservice).

webMethods Developer Users Guide Version 7.1.1

361

14 Subscribing to Events

Key pipeline

Description Acopyofthestateofthepipelineatthepointwheretheeventoccurred. NotethatthiselementisonlyincludedintheinputobjectiftheInclude pipelinepropertyissettoAlwaysorOn errors onlyorifthewatt.server.auditLog serverpropertyissettoverbose.FormoreinformationabouttheInclude pipelinepropertyintheAuditcategoryofthePropertiespanel,seeIncluding thePipelineintheAuditLogonpage 143. AStringcontainingtheusernamethatinvokedtheservicethatgenerated theevent.

user

Theauditeventhandlersthatyoubuildcanmakeuseoftheseinputsastheyneedto. KeepinmindthatwhentheservicesLog onoptionissettoError, success, and startanaudit eventhandleriscalledtwiceeachtimeaserviceruns:oncewhentheservicestartsand againwhenitends.Youreventhandlercancheckthevalueoftheresultparameterto determinewhetheritisprocessinganauditeventfrombeforeoraftertheservice executed.FormoreinformationabouttheLog onpropertyintheAuditcategoryofthe Propertiespanel,seeSpecifyingWhenAuditDataIsGeneratedonpage 142. Also,ifyoureventhandlerneedsdatafromtheinvokingservicespipeline,makesure thatservicesInclude pipelineoptionissettoAlwaysorOn errors only.Otherwise,thepipeline elementwontbeincludedintheinputobjectthatispassedtoyoureventhandler. Tip! Whenyousubscribeaneventhandlertoanauditevent,youcancreateafilterfor theservicefieldtospecifytheserviceswhoseauditeventsyouwanttosubscribeto. Thatis,youcanspecifywhichservicesauditeventsinvoketheeventhandler.

Working with Exception Events

Anexceptioneventoccurswhenaservicethrowsanexception(includingwhenaflow serviceexitsonfailure).Youcanuseexceptioneventstoinvokesomeprescribed action,suchasnotifyinganadministrator,whenaparticularservicefails. Note: Keepinmindthateventhandlersareprocessedindependentlyoftheservices thatinvokethem.Theyarecompletelyseparate,asynchronousprocesses.Event handlersarenotdesignedtoreplacetheerrorhandlingand/orerrorrecovery proceduresthatyouwouldnormallyincludeinyourservice. Ifanestedservicethrowsanexception,anexceptioneventisgeneratedbyeachservicein thecallstack.Forexample,ifserviceA1callsserviceB1,andB1throwsanexception, bothB1andA1generateexceptionevents(inthatorder).

362

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building Handlers for Exception Events

WhentheEventManagerinvokesaneventhandlerforanexceptionevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypeforthissignatureresideinthepub.eventfolder.) Key time Description AStringcontainingthedateandtimetheeventoccurred.Bydefault, theformatisyyyyMMddHH:mm:ssz.Youcansettheformatby specifyingthewatt.server.dateStampFmtproperty.Forinstructions abouthowtospecifyserverpropertysettings,seethewebMethods IntegrationServerAdministratorsGuide. AStringcontainingtheerrormessagefromtheexception. AStringcontainingtheerrormessagetextinthelanguagethat correspondstoyourlocale. AStringcontainingtheexceptiontypethatwasthrown. AStringcontainingmoredetailedinformationabouttheexception(if theexceptionobjectcontainsdumpinformation). AStringcontainingthefullyqualifiednameoftheservicethat generatedtheevent. AStringcontainingtheuserthatrequestedtheservicethatgenerated thisevent. Adocument(IDataobject)containingtheitemsinthecallstack.Seethe pub.event:callStackItemISdocumenttypeforthedefinitionofthe documentsincallStack. Acopyofthestateofthepipelineatthepointwhentheexception occurred. AStringidentifyingthethreadthatinvokedtheservice. AStringcontainingtheidentificationnumberofthesessionduring whichtheexceptionoccurred. AStringcontainingtheidentificationnumberfortheerrormessage. Adocument(IDataobject)containingadditionalexceptioninformation providedbytheauthoroftheJavaservice.Formoreinformationabout constructingexceptionstoreturnadditionalinformation,seethe webMethodsIntegrationServerJavaAPIReferenceforthe com.wm.util.LocalizedExceptionclass.

error localizedError errorType errorDump service user callStack

pipeline threadID ssnid errorMsgID errorDetails

nestedErrorInfo Adocument(IDataobject)containinganynestederrorsand exceptions.Seethepub.event:exceptionInfoISdocumenttypeforthe definitionoftheitemsinnestedErrorInfo.

webMethods Developer Users Guide Version 7.1.1

363

14 Subscribing to Events

Tip! Whenyousubscribeaneventhandlertoanexceptionevent,youcancreateafilter fortheservicefieldtospecifytheserviceswhoseexceptioneventsyouwantto subscribeto.Thatis,youcanspecifywhichservicesexceptioneventsinvokethe eventhandler.

Working with Guaranteed Delivery Events

Aguaranteeddeliveryeventoccurswhenaclientusesguaranteeddeliverytoinvokea serviceonaremoteIntegrationServer,andwhentheserverreturnstheserviceresultsto therequestingclient.Therearetwotypesofguaranteeddeliveryevents: GD Start eventsoccurwhenaclientusesguaranteeddeliverytoinvokeaserviceona remotetheIntegrationServer.Inaflowservice,executingthepub.remote.gd:startservice generatesaGDStartevent. GD End events occurwhenaclientreceivestheresultsoftheserviceitrequestedusing guaranteeddelivery.Inaflowservice,executingthepub.remote.gd:endservicegenerates aGDEndevent. EachguaranteeddeliverytransactiongeneratesaGDStarteventandaGDEndevent. YoucansubscribetoGDStartandGDEndeventstoinvokeeventhandlersthatlog guaranteeddeliverytransactionstoafileordatabase.Youmightalsowanttouse guaranteeddeliveryeventstoinvokeeventhandlersthatsendnotification.Forexample, ifyouuseguaranteeddeliverytoinvokeaservicethatprocessespurchaseorders,you mightwanttosendnotificationtoabusinessaccountmanageraboutpurchaseorders fromaparticularclient,orwhenthevalueofapurchaseorderisgreaterthanacertain amount.

Guaranteed Delivery Events and Transaction Events

Guaranteeddeliveryeventsarerelatedtotransactionevents(TxStartandTxEnd). Guaranteeddeliveryeventsbeginwhenaclientrequestsaguaranteeddelivery transaction(GDStart)andwhentheclientreceivestheresultsoftheguaranteeddelivery transaction(GDEnd).Transactioneventsoccurwhenaserviceinvokedusingguaranteed deliverybeginsexecuting(TxStartevent)andwhentheservicefinishesexecuting(Tx Endevent). Thefollowingdiagramillustrateswhenguaranteeddeliveryeventsandtransaction eventsoccurduringaguaranteeddeliverytransaction.Inthefollowingscenario,alocal IntegrationServerusesguaranteeddeliverytoinvokeaserviceonaremoteserver.

364

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

A Guaranteed Delivery Transaction generates Guaranteed Delivery Events and Transaction Events
webMethods Integration Server (local) 1 Service A 2 Service B webMethods Integration Server (remote)

Stage
1

Description ServiceAusesguaranteeddeliverytoinvokeServiceBontheremote IntegrationServer.WhenthelocalserverrequestsServiceB,thelocalserver generatesaGDStartevent.Bydefault,theGDStarteventisloggedtothe txoutyyyymmdd.logfile. TheremoteIntegrationServerreceivestherequestandbeginsexecuting ServiceB.WhentheremoteserverbeginsexecutingServiceB,theremote servergeneratesaTxStartevent.Bydefault,theTxStarteventisloggedto thetxinyyyymmdd.logfile. TheremoteIntegrationServerfinishesexecutingServiceBandgeneratesaTx Endevent.Bydefault,theTxEndeventisloggedtothetxinyyyymmdd.log file. TheremoteIntegrationServersendstheresultsofServiceBtotherequesting client(here,thelocalIntegrationServer). ThelocalIntegrationServerreceivestheresultsofServiceBandgeneratesa GDEndevent.Bydefault,theGDEndeventisloggedtothe txoutyyyymmdd.logfile.

4 5

Fordetailsaboutguaranteeddelivery,seetheGuaranteedDeliveryDevelopersGuide.

Building Handlers for Guaranteed Delivery Start Events

WhentheEventManagerinvokesaneventhandlerforaGDStartevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypefortheseparametersresideinthepub.eventfolder.) Key time TID Description AStringcontainingthedateandtimethattheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingthetransactionidentificationnumberoftheservice thatgeneratedtheGDStartevent.

webMethods Developer Users Guide Version 7.1.1

365

14 Subscribing to Events

Key svcname result

Description AStringcontainingthenameoftheserviceinvokedusingguaranteed delivery. AStringcontainingthestatusoftheguaranteeddeliverytransaction,such asNEW.

Tip! WhenyousubscribeaneventhandlertoaGDStartevent,youcancreateafilter forthesvcnamefieldtospecifytheservicesinaguaranteeddeliverytransactionthat youwanttosubscribeto.Thatis,youcanspecifytheservicesthatwheninvoked usingguaranteeddeliverywillinvoketheeventhandler.

Building Handlers for Guaranteed Delivery End Events

WhentheEventManagerinvokesaneventhandlerforanGDEndevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypefortheseparametersresideinthepub.eventfolder.) Key time TID result Description AStringcontainingthedateandtimethattheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingthetransactionidentificationnumberoftheservicethat generatedtheGDEndevent. AStringcontainingthestatusoftheguaranteeddeliverytransaction,suchas DONE.

Working with Port Status Events

AportstatuseventoccurseachtimetheIntegrationServerupdatestheserverstatistics. Theportstatuseventprovidescurrentstatusinformationaboutalloftheconfigured portsontheIntegrationServer. Youcanuseportstatuseventstoinvokeservicesthatsendportstatusdatatoanetwork monitoringsystem.Youcanalsouseportstatuseventstoinvokeservicesthatwriteport statusdatatoalogfile. Note: The watt.server.stats.pollTime propertydeterminesthefrequencywithwhichthe IntegrationServerupdatesserverstatistics.Thedefaultfrequencyis60seconds.If youchangethisvalue,youmustrestarttheIntegrationServerforthechangetotake effect.Formoreinformationaboutthisproperty,seethewebMethodsIntegrationServer AdministratorsGuide.

366

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building Handlers for Port Status Events

WhentheEventManagerinvokesaneventhandlerforaportstatusevent,theevent handlerreceivesanIDataobjectthatcontainsthefollowingruntimedata. (A specificationandanISdocumenttypewiththeseparametersareprovidedinthe pub.eventfolder.) Key portStatusInfo Description Adocumentreferencelistcontainingstatusinformationforeach configuredportontheIntegrationServer. String
time

Description AStringcontainingthedateandtimethattheevent occurred,intheformatyyyy/MM/dd HH:mm:ss.SS. AStringcontainingthenumberfortheport. AStringindicatingthestatusoftheport. AStringindicatingthetypeofport(forexample,http, https,ftp,oremail). AStringindicatingtheprimaryport.Bydefault,the IntegrationServerdesignatesanHTTPportatport5555as theprimaryport. AStringindicatingwhetherornottheportisenabled.The valuewillbeoneofthefollowing: String
true false

port status protocol

primary

enabled

Description Theportisenabled. Theportisdisabled.

Working with Replication Events

Areplicationeventoccurswhenthepub.replicator:generateReplicationEventserviceexecutes. Youmightwanttogenerateandsubscribetoreplicationeventstoinvokeeventhandlers thatautomatethecompletionofthepackagereplicationanddistributionprocesses.For example,youcouldcreatereplicationeventhandlersthatdothefollowing: Notifypackagesubscriberswhenapackageispublished. Maintainalogofreplicatedpackages. Maintainalogofthepackagesdistributedorpushedtoyoursubscribers. Maintainalogofthepackagesyourpartnerspulledfromyou. Formoreinformationaboutthepub.replicator:generateReplicationEventservice,seethe webMethodsIntegrationServerBuiltInServicesReference.

webMethods Developer Users Guide Version 7.1.1

367

14 Subscribing to Events

Building Handlers for Replication Events

WhentheEventManagerinvokesaneventhandlerforareplicationevent,theevent handlerreceivesanIDataobjectthatcontainsthefollowingruntimedata.(A specificationandanISdocumenttypefortheseparametersareprovidedinthepub.event folder.) Key time action Description AStringcontainingthedateandtimethattheeventoccurred,inthe formatyyyy/MM/dd HH:mm:ss.SS. AuserdefinedStringdescribingtheaction(suchascreateorpush)for thereplicationevent.Youcanusethevalueoftheactionvariableto maintainseparatelogsforeachactiontype. AStringcontainingthenameofthereleasedorpushedpackage. AStringcontainingthenameoftheflowservicethatinvokedthe pub.replicator:generateReplicationEventservice.

package service

Tip! Whenyousubscribeaneventhandlertoareplicationevent,youcancreateafilter tospecifythepackagethat,whenreplicated,willinvoketheeventhandler.

Working with Session Events

AsessioneventoccurswhenaclientstartsorendsasessionontheIntegrationServeror whentheIntegrationServerterminatesaninactivesession.Youcansubscribetoanyof thefollowingtypesofsessionevents: Session Start eventsoccurwhenadeveloperusesDevelopertoopenasessiononthe IntegrationServerorwhenanISclientopensasessionontheservertoexecute services. Session End eventsoccurwhenadeveloperorISclientspecificallyissuesadisconnect instructiontotheIntegrationServer. Session Expire eventsoccurwhentheIntegrationServerterminatesaninactivesession. Youcansubscribetosessioneventstoinvokeeventhandlersthatmaintainyourownlog filesortoinvokeeventhandlersthatsendnotificationaboutusersopeningsessionson theserver.

368

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building Handlers for Session Start Events

WhentheEventManagerinvokesaneventhandlerforasessionstartevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypefortheseparametersresideinthepub.eventfolder.) Key time sessionID userid sessionName Description AStringcontainingthedateandtimetheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingtheidentificationnumberofthesession. AStringcontainingtheuserIDthattheISclientordeveloperusedto logontotheIntegrationServer. AStringcontainingthenameofthenewsession.

Tip! WhenyousubscribeaneventhandlertoaSessionStartevent,youcancreatea filtersothatonlysessionstarteventsgeneratedbyaspecificuserorbyamemberofa specificgroupinvoketheeventhandler.

Building Handlers for Session End Events

WhentheEventManagerinvokesaneventhandlerforasessionendevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypefortheseparametersresideinthepub.eventfolder.) Key time sessionID rpcs age Description AStringcontainingthedateandtimethattheeventoccurred,inthe formatyyyy/MM/dd HH:mm:ss.SS. AStringcontainingtheidentificationnumberofthesession. AStringcontainingthenumberofservicecallsperformedduringthe session. AStringidentifyinghowlongthesessionexisted(inmilliseconds) beforeitended.

webMethods Developer Users Guide Version 7.1.1

369

14 Subscribing to Events

Building Handlers for Session Expire Events

WhentheEventManagerinvokesaneventhandlerforasessionexpireevent,theevent handlerreceivesanIDataobjectcontainingthefollowingruntimedata.(Aspecification andanISdocumenttypefortheseparametersresideinthepub.eventfolder.) Key time sessionID rpcs age Description AStringcontainingthedateandtimetheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingtheidentificationnumberofthesession. AStringcontainingthenumberofservicecallsperformedduringthe session. AStringidentifyinghowlongthesessionexisted(inmilliseconds) beforeitexpired.

Working with Stat Events

AstateventoccurseachtimetheIntegrationServerupdatesthestatisticslog(stats.log). Thestatisticslogmaintainsstatisticalinformationabouttheconsumptionofsystem resources.The watt.server.stats.pollTime propertydeterminesthefrequencywithwhichthe IntegrationServerupdatesstatistics.Thedefaultfrequencyis10seconds. Youcanusestateventstoinvokeeventhandlersthatmaintainyourownlogfileorto invokeeventhandlersthatsendserverstatisticstoanetworkmonitoringsystem. Note: TheIntegrationServerprovidesanagentthatyoucanconfigureforusewitha networkmonitoringsystem.Forinformationaboutimplementingthisagent,seethe readmefileintheagentInstall.jarfilelocatedintheIntegrationServer_directory\lib directory.

Building Handlers for Stat Events

WhentheEventManagerinvokesaneventhandlerforastatevent,theeventhandler receivesanIDataobjectcontainingthefollowingruntimedata.(AspecificationandanIS documenttypefortheseparametersresideinthepub.eventfolder.) Key startTime uptime Description AStringcontainingthedateandtimethattheeventoccurred,inthe formatyyyy/MM/dd HH:mm:ss.SS. AStringidentifyingthelengthoftimetheserverhasbeenrunning,in theformatyyyy/MM/dd HH:mm:ss.SS.

370

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Key totalMem freeMem usedMem freeMemPer usedMemPer svrT svrTMax sysT sysTMax conn connMax reqTotal reqAvg newReqPM endReqPM errSvc svcRate ssnUsed ssnPeak ssnMax errSys

Description AStringidentifyingthetotalamountofusedandunusedstorage spaceavailable(inkilobytes)totheIntegrationServer. AStringidentifyingtheamountofunusedstoragespaceavailable(in kilobytes)totheIntegrationServer. AStringidentifyingtheamountofstorageused(inkilobytes)bythe IntegrationServer. AStringidentifyingthepercentageoffreememory. AStringidentifyingthepercentageofusedmemory. AStringidentifyingthenumberofexecutingservices. AStringidentifyingthemaximumnumberofservicesthatexecuted concurrentlyduringthepreviouspollcycle. AStringidentifyingthenumberofthreadsinuse. AStringidentifyingthemaximumnumberofthreadsthatexecuted concurrentlyduringthepreviouspollcycle. AStringidentifyingthenumberofcurrentsessionsontheIntegration Server. AStringidentifyingthemaximumnumberofconnectionsthatran concurrentlyduringthepreviouspollcycle. AStringidentifyingthetotalnumberofrequestsduringthepollcycle. AStringidentifyingtheaverageprocessingdurationforaservice duringthepreviouspollcycle. AStringidentifyingthenewrequestsperminuteatthebeginningof thepollcycle. AStringidentifyingthenewrequestsperminuteattheendofthepoll cycle. AStringidentifyingthenumberofservicesthatcompletedwitherrors sincetheIntegrationServerstarted. AStringidentifyingthenumberofservicestartsandendspersecond duringthelastpollcycle. Numberoflicensedsessionscurrentlyactive. Greatestnumberoflicensedsessionsthathaverunconcurrentlyonthe server. Maximumnumberofsessionsforwhichtheserverislicensed. AStringidentifyingthenumberoferrorsthatwerenotcausedby servicesinthepreviouspollcycle.

webMethods Developer Users Guide Version 7.1.1

371

14 Subscribing to Events

Working with Transaction Events

AtransactioneventoccurswhenanIntegrationServerbeginsandfinishesexecutinga guaranteeddeliverytransaction.Therearetwotypesoftransactionevents: Tx Start eventsoccurwhenanIntegrationServerbeginsexecutingaserviceinvoked withguaranteeddelivery. Tx End events occurwhenanIntegrationServerfinishesexecutingaserviceinvoked withguaranteeddelivery. Transactioneventsresultfromguaranteeddeliverytransactions.Eachguaranteed deliverytransactiongeneratesaTxStarteventandaTxEndevent.Infact,thetransaction eventsoccurbetweentheguaranteeddeliveryevents.ATxStarteventoccurs immediatelyafteraGDStarteventandaTxEndeventoccursimmediatelybeforeaGD Endevent.Formoreinformationabouthowtransactioneventsrelatetoguaranteed deliveryevents,seeGuaranteedDeliveryEventsandTransactionEventsonpage 364. YoucansubscribetoTxStartandTxEndeventstoinvokeeventhandlersthatlog guaranteeddeliverytransactionstoafileordatabase.Youmightalsowanttouse transactioneventstoinvokeeventhandlersthatsendnotification.

Building Handlers for Transaction Start Events

WhentheEventManagerinvokesaneventhandlerforaTxStartevent,theeventhandler receivesanIDataobjectcontainingthefollowingruntimedata.(AspecificationandanIS documenttypefortheseparametersresideinthepub.eventfolder.) Key time TID result Description AStringcontainingthedateandtimethattheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingthetransactionIDfortheguaranteeddelivery transactionthatgeneratedtheevent. AStringcontainingthestatusoftheguaranteeddeliverytransaction,such asNEW.

372

webMethods Developer Users Guide Version 7.1.1

14 Subscribing to Events

Building Handlers for Transaction End Events

WhentheEventManagerinvokesaneventhandlerforaTxEndevent,theeventhandler receivesanIDataobjectcontainingthefollowingruntimedata.(AspecificationandanIS documenttypefortheseparametersresideinthepub.eventfolder.) Key time TID result Description AStringcontainingthedateandtimethattheeventoccurred,intheformat yyyy/MM/dd HH:mm:ss.SS. AStringcontainingthetransactionIDoftheguaranteeddelivery transactionthatgeneratedtheevent. AStringcontainingthestatusoftheguaranteeddeliverytransaction,such asDONE.

webMethods Developer Users Guide Version 7.1.1

373

14 Subscribing to Events

374

webMethods Developer Users Guide Version 7.1.1

15

Building Services that Retry

376 376 377

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

375

15 Building Services that Retry

Overview
Whencreatingaservice,youcanconstructandconfiguretheservicetoretry automaticallyifatransienterroroccursduringserviceexecution.Atransienterrorisan errorthatarisesfromatemporaryconditionthatmightberesolvedorrestored,suchas theunavailabilityofaresourceduetonetworkissuesorfailuretoconnecttoadatabase. TheservicemightexecutesuccessfullyiftheIntegrationServerwaitsashortintervalof timeandthenretriestheservice. TosignaltheIntegrationServertoreexecutetheservice,youcanbuildtheserviceto throwanISRuntimeExceptionwhenatransienterroroccurs.Then,ifaserviceends becauseofanISRuntimeExceptionandyousetretrypropertiesfortheservice(orthe triggercallingtheservice),IntegrationServerwillreexecutetheserviceusingthe originalserviceinput. Thisappendixprovidesguidanceforbuildingflowservicesthatretryifatransienterror occursduringserviceexecution.

Requirements for Retrying

Ifyouwantaservicetocatchatransienterror,rethrowitasanISRuntimeException,and thenreexecute,thefollowingcriteriamustbemet: YoumustconfiguretheRetry on ISRuntimeExceptionpropertiesforthetoplevelservice. FormoreinformationaboutconfiguringserviceretryandhowtheIntegrationServer retriesservices,seeConfiguringServiceRetryonpage 135. Iftheservicefunctionsasatriggerservice(theserviceisinvokedbyatrigger),you mustconfiguretheTransient error handlingpropertiesforthetrigger.Formore informationaboutconfiguringretryforBroker/localtriggers,seethePublishSubscribe DevelopersGuide.ForinformationaboutconfiguringretryforJMStriggers,seethe webMethodsIntegrationServerJMSClientDevelopersGuide. Iftheserviceisaflowservice,theservicemustinvoke pub.flow:throwExceptionForRetry. IftheserviceiswritteninJava,theservicecanuse com.wm.app.b2b.server.ISRuntimeException().

Adapter Services and Retry Behavior

AdapterservicesbuiltonIntegrationServer6.0orlater,andbasedontheART framework,detectandpropagateexceptionsthatsignalaretryifatransienterroris detectedontheirbackendresource.Atruntime,adapterservicesdetectiftheirbackend serverisdownorthenetworkconnectionisbroken.Theadapterservicepropagatesan exceptionthatisbasedonISRuntimeException.Thisbehaviorallowsfortheautomatic retrywhentheserviceisinvokedbyatriggerorinvokedwithinaflowthatisconfigured toretrywhenanISRuntimeExceptionoccurs.

376

webMethods Developer Users Guide Version 7.1.1

15 Building Services that Retry

Note: Ifyouinvokeanadapterservicewithinaflowservicethatusesthetrycatch structure,andthetrycontainsanadapterservice,makesurethatthecatchstructure caninterprettheadapterserviceexceptionthatsignalsaretry.Youmustensurethat theerrorevaluatinglogicinthecatchstructurecanaccountfortheadapterservice exceptionthatsignalsaretry.Ifitdoesnot,theIntegrationServerwillnotretrythe flowservice.Fordetailsaboutbuildingaflowservicethatthrowsan ISRuntimeException,seeBuildingaServicethatThrowsanExceptionforRetry, below. Formoreinformationaboutadapterservices,seetherelevantadapterguides.

Building a Service that Throws an Exception for Retry

Aflowservicethatwillberetriedifatransienterroroccursduringserviceexecution consistsofthefollowingbasicsectionsoflogic: Atrysequencethatexecutestheworkthatyouwanttheservicetoperform. Acatchsequencethathandlesanyexceptionthatoccursduringthetrysequence, determinesifatransienterrorcausedtheexception,andindicateswhetherthe IntegrationServersshouldretrytheservice. Anoutersequencethatexitssuccessfullyifeitherthetrysequenceorcatchsequence succeeds. Athrowexceptionforretryblockthatexecutesonlyifthecatchblockindicatedthat theserviceshouldberetried. Note: Thissectiondescribesonepossiblewaytobuildaservicethatthrowsan exceptionforretry.

How to Build a Service that Throws an Exception for Retry

Thefollowingdescribesthegeneralstepsthatyoutaketobuildaservicethatwillretryif atransienterroroccursduringserviceexecution. 1 Insert a SEQUENCE step.ThisSEQUENCEstepwillactastheoutersequenceforthetry sequenceandthecatchsequence. SetthisouterSEQUENCEtoexitonSUCCESS.Thisindicatesthatthesequencewill exitwhenanychildstepinthesequencesucceeds.Iftheinnertrysequence(thefirst childofthisparentSEQUENCE)succeeds,thentheinnercatchsequencewillbe skipped,anISRuntimeExceptionwillnotbethrown,andtheentireservicewillhave executedsuccessfully.

webMethods Developer Users Guide Version 7.1.1

377

15 Building Services that Retry

Insert an inner SEQUENCE step for the try sequence. Thissequencewillcontainthelogic thatyouwanttheservicetoperform. SetthisinnertrysequencetoexitonFAILURE.Thisindicatesthatthetrysequence willexitwhenastepintheSEQUENCEfails.TheIntegrationServerwillthenexecute thenextstepintheflowservice,whichisthecatchsequence. Makesurethatthetrysequenceisachildoftheoutersequencethatyouinsertedin step 1.

Insert the logic that you want the service to perform.Thesestepscontaintheworkthatyou wanttheservicetodo. Makesuretoindentthestepsbelow/underthetrySEQUENCEstep. Insert a SEQUENCE step for the catch sequence.Thissequencecontainsthestepsneeded tocatchtheexception,determineitscause,andthendeterminewhethertheservice canberetried. SetthecatchsequencetoexitwhenDONE.ThisindicatesthattheIntegrationServer executeseverystepinthecatchsequence,evenifoneofthestepsfails. Makesurethatthecatchsequenceisachildoftheoutersequencethatyouinsertedin step 1.

Invoke pub.flow:getLastError in the catch sequence to retrieve error information.Thisservice retrievesinformationaboutthelastexceptionthatoccurredintheflowservice.Inthis case,thepub.flow:getLastErrorserviceretrievesinformationabouttheerrorthatcaused thetrysequencetofail. Makesuretoindentthepub.flow:getLastErrorinvokestepbelowthecatchSEQUENCE step. Usingpub.flow:getLastErrortocatchtheerrorinformationisoptional. Important! Thepub.flow:getLastErrorservicemustbethefirstserviceinvokedwithin thecatchsequence.Ifitisnotthefirstserviceinvoked,andaprecedingservicein thecatchsequencefails,theerrorthrowninthetrysequencewillbeoverwritten withthenewerror.

Insert error evaluation logic. Thislogicshoulddothefollowing:

Determinewhetherthelasterrorisatransienterrorthatcanberetried. Note: Iftheflowserviceincludesanadapterservice,andatransienterror occursduringadapterserviceexecution,theadapterservicethrowsan exceptionthatextendstheISRuntimeException.

Iftheservicecanberetried,setaflagtoindicatethis.Forexample,youmightseta variablenamedisTransientErrortotrue.AsubsequentBRANCHstepwilluse theflagtodeterminewhethertoexecutethepub.flow:throwExceptionForRetryService.

Keepinmindthatyoumightneedtousemorethanoneservicetohandletheerror, determineifitwascausedbyatransienterror,andsetthetransienterrorflag.

378

webMethods Developer Users Guide Version 7.1.1

15 Building Services that Retry

Makesuretoinserttheexceptionevaluationlogicwithinthecatchsequence,butafter thepub.flow:getLastErrorservice. 7 Insert a BRANCH step that branches on the value of the transient error flag. ThisBRANCH stepwilldetermineifanISRuntimeExceptionshouldbethrown.Youcanbranchona switchvalueorbranchonanexpression.Dooneofthefollowing:

Ifyouarebranchingonaswitchvalue,intheSwitchproperty,specifythenameof thepipelinevariablewhosevaluewillactastheswitch.Forexample,ifyouuse theisTransientErrorvariableastheflagtoindicatethatatransienterroroccurred, youwoulduseisTransientErrorastheswitch. Ifyouarebranchingonanexpression,settheEvaluate labelspropertytoTrue. Important! YoumustpositiontheBRANCHstepsothatitisoutsideofthetryand catchsequencesandisasiblingoftheoutersequence.Thisisbecauseexceptions thrownwithinasequenceareignoredandtheBRANCHstepwillcontainthe pub.flow:throwExceptionForRetryservice.

Invoke the pub.flow:throwExceptionForRetry service. Thisservicewrapsanexceptionand rethrowsitasanISRuntimeException. Assignthisservicealabelthatindicatesthatthisstepshouldexecutewhenthe transienterrorflagistrue.Forexample,ifyoubuilttheBRANCHsteptouse isTransientErrorissettotruewhenatransienterroroccurredandyouwantthe IntegrationServertoretrytheservice,settheLabelpropertyto:true. MakesurethatthisstepisachildoftheBRANCHstep. Youcanalsoprovidethefollowingoptionalparameterstothe pub.flow:throwExceptionForRetryservice. Name wrappedException Description AnObjectcontaininganyexceptionthatyouwanttoinclude aspartofthisISRuntimeException.Thismightbethe exceptionthatcausesthepub.flow:throwExceptionForRetryservice toexecute.Forexample,iftheserviceattemptstoconnecttoa databaseandtheconnectionattemptfails,youmightmapthe exceptiongeneratedbythedatabaseconnectionfailuretothe wrappedExceptionparameter. Astringcontainingamessagetobeloggedaspartofthis exception.

message

Note: Ifyouwanttoinsertretrylogicintoaservicethatmakesdatabasecallsor involvestransactions,yourserviceneedstoincludelogicforstarting,committing, androllingbackthetransaction.Specifically,therollbackcallshouldbemadeinthe catchsequence.

webMethods Developer Users Guide Version 7.1.1

379

15 Building Services that Retry

ExampleBuilding a Service that Throws an Exception for Retry

Thefollowingflowserviceexecutesanestedservice,catchesanyexceptionthatoccurs, determinesifatransienterrorcausedtheexception,and,ifnecessary,throwsan ISRuntimeExceptionsothattheentireservicecanberetried. Trying a service, catching an error, and throwing an exception for retry

# Step 1

Description Create outer SEQUENCE that exits on SUCCESS.Thisstepcreatesasequencethat wrapsthetrysequenceandthecatchsequence.Thesequenceissettoexiton successsothattheoutersequencewillexitwhenachildstepexecutes successfully.Thatis,settingtheoutersequencetoexitonsuccessallowsthe outersequencetoexitwithoutexecutingthecatchsequencewhenthetry sequencesucceeds. Step 1.1 Description Create try SEQUENCE that exits on FAILURE.Thisstepcreatesthetry sequencethatcontainsallofthelogicyouwanttheservicetoexecute. ThisstepissettoexitonfailuresothattheIntegrationServerwill executethenextstep(thecatchsequence)withintheoutersequence.

380

webMethods Developer Users Guide Version 7.1.1

15 Building Services that Retry

Description Step 1.1.1 Description Insert service logic. Thissteprepresentsthelogicthatyouwant theservicetoperform.Inmanyservices,theservicelogic mightconsistofmultipleservicesorflowsteps. Ifthetrysequenceexecutessuccessfully,theentireouter sequenceexits.TheIntegrationServerskipsthecatchsequence becausetheoutersequenceexitsuponthesuccessofanychild step(inthiscase,thetrysequence).TheIntegrationServer thenexecutesthenextstepintheflowservice(theBRANCH on/isTransientErrorstep). Ifanerroroccurswhileexecutingthisstep,thetrysequence exits(itissettoexitonFAILURE),andtheIntegrationServer executesthecatchsequence. 1.2 Create catch SEQUENCE that exits on DONE. Thisstepcreatesthecatch sequencethatcontainsthelogicthatshouldbeperformedwhenan erroroccursduringthetrysequence.Thisstepcontainslogicthat evaluatestheerrortodeterminewhethertheentireservicecanbe retried. ThecatchsequenceissettoexitonDONE.Thismeansthatthe IntegrationServerexecutesallthestepsinthecatchsequence.The IntegrationServerconsidersthecatchsequencetobesuccessfulafterall thechildstepsexecute.Becausethecatchsequenceissuccessful,the outersequenceexits(itissettoexitonSUCCESS),andtheIntegration Serverexecutesthenextstepintheflowservice. Todeterminewhetheratransienterroroccurred,thisstepcontainsthe followingsteps. Step 1.2.1 1.2.2 Description Catch the last error.Thisstepinvokesthepub.flow:getLastError servicetocatchtheerrorthatcausedthetrysequencetofail. Determine if error was a transient error.Thisstepevaluatesthe contentsofthelastErrordocumentreturnedbythe pub.flow:getLastErrorservicetodeterminewhetherthetry sequencefailedbecauseofatransienterror.Inmanyservices, youmightusemultipleservicesorflowstepstodetermine whetheratransienterroroccurred.

webMethods Developer Users Guide Version 7.1.1

381

15 Building Services that Retry

Description 1.2.3 Set flag to indicate whether service should retry.Thisstepsetsthe transienterrorflagtoindicateifatrysequencefailedbecause ofatransienterror.Inthiscase,ifatransienterroroccurred, thetransienterrorflag(thevariableisTransientError)issetto true. Afterthisstepexecutes,theIntegrationServerexitsthecatch sequence,exitstheoutersequence,andthenexecutesthenext stepintheflowservice(theBRANCHon/isTransientError step).

Step 2

Check transient error flag. ThisstepspecifiesthatthevalueoftheisTransientError variableshouldbeusedtodeterminewhethertheserviceshouldthrowan ISRuntimeException. Ifthetrysequenceexecutedsuccessfully,theIntegrationServerfallsthrough totheendoftheservicebecausethevalueoftheswitchvariabledoesnot matchanyofthetargetsteps(ifthetrysequencesucceeded,isTransientErroris null).Inthiscase,theIntegrationServerconsiderstheexecutionoftheflow servicetobesuccessful. Step 2.1 Description Throws ISRuntimeException. Thisstepexecutesthe pub.flow:throwExceptionForRetryserviceifthevalueofisTransientErroris true.Thisservicewrapstheexceptiongeneratedbythetransient errorinthetrysequenceandrethrowsitasanISRuntimeException. TheIntegrationServerwillretrytheservice.

382

webMethods Developer Users Guide Version 7.1.1

webMethods Flow Steps

384 386 388 389 390 391 394

BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

383

A webMethods Flow Steps

BRANCH
TheBRANCHstepselectsandexecutesachildstepbasedonthevalueofoneormore variablesinthepipeline.Youindicatethevariablesyouwanttobranchonbyspecifyinga switchvalueorbywritinganexpressionthatincludesthevariables.

Branching on a Switch Value

Whenyoubranchonaswitchvalue,youspecifytheswitchvariableintheSwitch propertyoftheBRANCHstep.IntheLabelpropertyforeachchildstep,youspecifythe valueoftheswitchvariablethatwillcausethatchildsteptoexecute.Atruntime,the BRANCHflowstepexecutesthechildstepthathasthesamelabelasthevalueofthe Switchproperty. IfyouwanttoexecuteachildstepwhenthevalueoftheSwitchpropertyisanempty string,leavetheLabelpropertyofthechildstepblank.Ifyouwanttoexecuteachildstep whentheSwitchpropertyisanullorunmatchedstring,settheLabelofthechildstepto $nullor$default. BRANCH flow step using a switch
if the value of choice is if the value of choice is Name1 Name2

Name of the switch field is choice

if the value of choice is if choice does not exist or has a value of $null if the value of choice is an empty string Otherwise

NameN $null no $defaul

Branching on Expressions
Whenyoubranchonexpressions,yousettheEvaluate labelspropertyoftheBRANCH steptotrue.IntheLabelpropertyforeachchildstep,youwriteanexpressionthat includesoneormorevariables.Atruntime,theBRANCHstepexecutesthefirstchild stepwithanexpressionthatevaluatestotrue. Ifyouwanttospecifyachildsteptoexecutewhennoneoftheexpressionsaretrue,set thelabelofthechildstepto$default.

384

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

BRANCH step using expressions

if the expression of first child is if the expression of second child is true Child1 Child2

Evaluate labels is set to true if the expression of nth child is Otherwise

ChildN $defau

TheBRANCHstepinthefollowingillustrationevaluatesexpressionstodeterminewhich childstepsexecute.TheruntimevalueofBuyerAccount,PromotionalCode,or shippingMethoddeterminestheshippingchargesaddedtoanorder. Simple BRANCH step using expressions

Properties
TheBRANCHstephasthefollowingproperties. Property Comments Scope Description Optional.Specifiesadescriptivecommentforthestep. Optional.Specifiesthenameofadocument(IDataobject)inthe pipelinetowhichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstep shouldrun.Ifthistimeelapsesbeforethestepcompletes,theserver waitsforthesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty,type thevariablenamebetween%symbols.Forexample,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank.

Timeout

webMethods Developer Users Guide Version 7.1.1

385

A webMethods Flow Steps

Property Label

Description Optional.(RequiredifyouareusingthisBRANCHstepasatargetfor anotherBRANCHorEXITstep.)Specifiesanameforthisinstanceof theBRANCHstep,oranull,unmatched,oremptystring($null, $default,blank). SpecifiestheStringfieldthattheBRANCHstepusestodetermine whichchildflowsteptoexecute.TheBRANCHstepexecutesthechild flowstepwhoselabelmatchesthevalueofthefieldspecifiedinthe Switchproperty.DonotspecifyavalueifyousettheEvaluate labels propertytoTrue. Specifieswhetherornotyouwanttheservertoevaluatelabelsofchild stepsasconditionalexpressions.Whenyoubranchonexpressions,you enterexpressionsintheLabelpropertyforthechildrenoftheBRANCH step.Atruntime,theserverexecutesthefirstchildstepwhoselabel evaluatestoTrue.Tobranchonexpressions,selectTrue.Tobranchonthe Switchvalue,selectFalse.

Switch

Evaluate labels

Conditions that Will Cause a BRANCH Step to Fail

TheswitchfieldisnotinthepipelineandtheBRANCHstepdoesnotcontaina defaultchildsteporachildsteptohandlenullvalues. Thematchingchildstepfails. TheBRANCHstepdoesnotcompletebeforethetimeoutperiodexpires.

EXIT
TheEXITstepexitstheentireflowserviceorasingleflowstep.Specifically,itmayexit fromthenearestancestorloopstep,aspecifiedancestorstep,theparentstep,orthe entireflowservice. TheEXITstepcanthrowanexceptioniftheexitisconsideredafailure.Whenan exceptionisthrown,userspecifiederrormessagetextisdisplayedbytypingitdirectlyor byassigningittoavariableinthepipeline.

386

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

Properties
TheEXITstephasthefollowingproperties. Property Comments Label Description Optional.Specifiesadescriptivecommentforthestep. Optional.(RequiredifyouareusingthisEXITstepasatargetfora BRANCHstep.)Specifiesanameforthisspecificstep,oranull, unmatched,oremptystring($null,$default,blank). Required.Specifiestheflowsteporservicefromwhichyouwantto exit. Specify this value $parent $loop $flow label To exit the Parentflowstep,regardlessofthetypeofstep. NearestparentLOOPorREPEATstep. Entireflow. Nearestancestorstepthathasalabelthat matchesthisvalue. Note: Ifthelabelyouspecifydoesnotmatchthe labelofanancestorflowstep,theflowwillexit withanexception. Signal Required.Specifieswhethertheexitisconsideredasuccessora failure.ASUCCESSconditionexitstheflowserviceorstep.AFAILURE conditionexitstheflowserviceorstepandthrowsanexception.The textoftheexceptionmessageiscontainedintheFailure message property. Optional.Specifiesthetextoftheexceptionmessagethatisdisplayed whenSignalissettoFAILURE.Ifyouwanttousethevalueofapipeline variableforthisproperty,typethevariablenamebetween%symbols. Forexample,%mymessage%.

Exit from

Failure message

Examples of When to Use

Exitanentireflowservicefromwithinaseriesofdeeplynestedsteps. Throwanexceptionwhenyouexitaflowserviceoraflowstepwithouthavingto writeaJavaservicetocallService.throwError(). ExitaLOOPorREPEATflowstepwithoutthrowinganexception.

webMethods Developer Users Guide Version 7.1.1

387

A webMethods Flow Steps

INVOKE
TheINVOKEflowstepinvokesanotherservice.Youcanuseittoinvokeanytypeof service,includinganotherflowservice.

Properties
TheINVOKEstephasthefollowingproperties. Property Comments Scope Description Optional.Specifiesadescriptivecommentforthestep. Optional.Specifiesthenameofadocument(IDataobject)inthe pipelinetowhichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstep shouldrun.Ifthistimeelapsesbeforethestepcompletes,theserver waitsforthesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty, typethevariablenamebetween%symbols.Forexample, %expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank. Label Optional.(Requiredifyouareusingthisstepasatargetfora BRANCHorEXITstep.)Specifiesanameforthisspecificstep,ora null,unmatched,oremptystring($null,$default,blank). Required.Specifiesthefullyqualifiednameoftheservicetoinvoke. Optional.Specifieswhethertheservervalidatestheinputtothe serviceagainsttheserviceinputsignature.Ifyouwanttheinputtobe validated,selectTrue.Ifyoudonotwanttheinputtobevalidated, selectFalse. Optional.Specifieswhethertheservervalidatestheoutputofthe serviceagainsttheserviceoutputsignature.Ifyouwanttheoutputto bevalidated,selectTrue.Ifyoudonotwanttheoutputtobevalidated, selectFalse.

Timeout

Service Validate input

Validate output

Conditions that Will Cause an INVOKE Step to Fail

Theservicethatisinvokedfails. Thespecifiedservicedoesnotexist. Thespecifiedserviceisdisabled.

388

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

LOOP
TheLOOPsteptakesasinputanarrayvariablethatisinthepipeline.Itloopsoverthe membersofaninputarray,executingitschildstepseachtimethroughtheloop.For example,ifyouhaveaservicethattakesastringasinputandastringlistinthepipeline, usetheLOOPsteptoinvoketheserviceonetimeforeachstringinthestringlist. Youidentifyasinglearrayvariabletouseasinputwhenyousetthepropertiesforthe LOOPstep.Youcanalsodesignateasinglevariableforoutput.TheLOOPstepcollects anoutputvalueeachtimeitrunsthroughtheloopandcreatesanoutputarraythat containsthecollectedoutputvalues.Ifyouwanttocollectmorethanonevariable, specifyadocumentthatcontainsthefieldsyouwanttocollectfortheoutputvariable. The LOOP step
No more input array members? Yes get next member of input array

input is an array

child

child

child

Properties
TheLOOPstephasthefollowingproperties. Property Comments Scope Description Optional.Specifiesadescriptivecommentforthestep. Optional.Specifiesthenameofadocument(IDataobject)inthe pipelinetowhichyouwanttorestrictthisstep.Ifyouwantthisstepto haveaccesstotheentirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstep shouldrun.Ifthistimeelapsesbeforethestepcompletes,theserver waitsforthesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty,type thevariablenamebetween%symbols.Forexample,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank.

Timeout

webMethods Developer Users Guide Version 7.1.1

389

A webMethods Flow Steps

Property Label

Description Optional.(RequiredifyouareusingthisstepasatargetforaBRANCH orEXITstep.)Specifiesanameforthisspecificstep,oranull, unmatched,oremptystring($null,$default,blank). Required.Specifiestheinputarrayoverwhichtoloop.Youmust specifyavariableinthepipelinethatisanarraydatatype(thatis, Stringlist,Stringtable,documentlist,orObjectlist). Optional.Specifiesthenameofthefieldinwhichtheserverplaces outputdataforaniterationoftheloop.Theservercollectstheoutput fromtheiterationsintoanarrayfieldwiththesamename.Youdonot needtospecifythispropertyiftheloopdoesnotproduceoutputvalues.

Input array

Output array

Conditions that Will Cause a LOOP Step to Fail

Thepipelinedoesnotcontaintheinputarray. Theinputfieldisnotanarrayfield. AchildstepoftheLOOPstepfailsduringanyiterationoftheloop. TheLOOPstepdoesnotcompletebeforethetimeoutperiodexpires.

MAP
TheMAPstepadjuststhepipelineatanypointinaflow.Itmakespipelinemodifications thatareindependentofanINVOKEstep. WithintheMAPstep,youcan: Link(copy)thevalueofapipelineinputfieldtoaneworexistingpipelineoutput field. Dropanexistingpipelineinputfield.(Keepinmindthatonceyoudropafieldfrom thepipeline,itisnolongeravailabletosubsequentservicesintheflow.) Assignavaluetoapipelineoutputfield. Performdocumenttodocumentmappinginasingleviewbyinsertingtransformers.

390

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

Properties
TheMAPstephasthefollowingproperties. Property Comments Scope Description Optional.Specifiesadescriptivecommentforthisstep. Optional.Specifiesthenameofadocument(IData)inthepipelinetowhich youwanttorestrictthisstep.Ifyouwantthissteptohaveaccesstothe entirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstepshould run.Ifthistimeelapsesbeforethestepcompletes,theserverwaitsforthe steptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty,typethe variablenamebetween%symbols.Forexample,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank. Label Optional.(RequiredifyouareusingthisstepasatargetforaBRANCHor EXITstep.)Specifiesanameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank).

Timeout

Example of When to Use

Youwanttoassignaninitialsetofinputvaluesinaflowservice(thatis,toinitialize variables).YouinserttheMAPstepatthebeginningoftheflow,andthenusetheSet ValuemodifiertoassignvaluestotheappropriatevariablesinPipeline Out. Youwanttomapadocumentfromoneformattoanother(forexample,cXMLto XML).InserttransformersintotheMAPsteptoperformtheneededdata transformations.Formoreinformationabouttransformers,seeWhatAre Transformers?onpage 212.

REPEAT
TheREPEATsteprepeatedlyexecutesitschildstepsuptoamaximumnumberoftimes thatyouspecify.ItdetermineswhethertoreexecutethechildstepsbasedonaRepeat on condition.Youcansettherepeatconditiontooneofthefollowing: Repeatifanyoneofthechildstepsfails. Repeatifalloftheelementssucceed. YoucanalsospecifyatimeperiodthatyouwanttheREPEATflowsteptowaitbeforeit reexecutesitschildsteps.

webMethods Developer Users Guide Version 7.1.1

391

A webMethods Flow Steps

The REPEAT step

reps=0 child reps = reps + 1 child child

wait for repeat interval

Yes

reps < Count ? No Exit

Yes

Repeat condition met?

No

Exit

Properties
TheREPEATstephasthefollowingproperties. Property Comments Scope Description Optional.Specifiesadescriptivecommentforthisstep. Optional.Specifiesthenameofadocument(IDataobject)inthepipeline towhichyouwanttorestrictthisstep.Ifyouwantthissteptohaveaccess totheentirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstepshould run.Ifthistimeelapsesbeforethestepcompletes,theserverwaitsforthe steptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty,type thevariablenamebetween%symbols.Forexample,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank. Label Optional.(RequiredifyouareusingthisstepasatargetforaBRANCHor EXITstep.)Specifiesanameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank). Required.Specifiesthemaximumnumberoftimestheserverreexecutes thechildstepsintheREPEATstep.SetCountto0(zero)toinstructthe serverthatthechildstepsshouldnotbereexecuted.SetCounttoavalue greaterthanzerotoinstructtheservertoreexecutethechildstepsuptoa specifiednumberoftimes.SetCountto-1toinstructtheservertore executethechildstepsaslongasthespecifiedRepeat onconditionistrue. Ifyouwanttousethevalueofapipelinevariableforthisproperty,type thevariablenamebetween%symbols.Forexample,%servicecount%.

Timeout

Count

392

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

Property Repeat interval

Description Optional.Specifiesthenumberofsecondstheserverwaitsbeforere executingthechildsteps.Specify0(zero)toreexecutethechildsteps withoutadelay. Ifyouwanttousethevalueofapipelinevariableforthisproperty,type thevariablenamebetween%symbols.Forexample,%waittime%.

Repeat on

Required.SpecifieswhentheserverreexecutestheREPEATchildsteps. SelectSUCCESStoreexecutethechildstepswhentheallthechildsteps completesuccessfully.SelectFAILUREtoreexecutethechildstepswhen anyoneofthechildstepsfails.

When Does REPEAT Fail?

ThefollowingconditionscausetheREPEATsteptofail: If Repeat on is set to SUCCESS FAILURE The REPEAT step fails if AchildwithintheREPEATblockfails. TheCountlimitisreachedbeforeitschildrenexecute successfully.

IftheREPEATstepisachildofanotherstep,thefailureispropagatedtoitsparent.

Examples of When to Use

Repeat on property is set to FAILURE. Usewhenaserviceaccessesaremoteserverand youwanttheservicetoretryiftheserverisbusy.Maketheservicethataccessesthe remoteserverachildelementofaREPEATflowstep,andthensettheRepeat on propertytoFAILURE.IftheserviceattemptstoaccesstheWebsiteanditfails,the REPEATflowstepattemptstoretrytheserviceagain.YoualsosetaRepeat intervalthat causestheREPEATflowconditiontowaitaperiodoftimebeforeinvokingthe serviceagain. Repeat on property is set to SUCCESS.UseinaWebautomationservicewhenyouwant torepeataloadandquerystepandaNextPagebuttonexistsinthecurrent document,indicatingthatthereareadditionalpagestobeprocessed.Endthe REPEATflowstepwhenthequerystepfailstoretrieveaNextPagebuttoninthe currentdocument.

webMethods Developer Users Guide Version 7.1.1

393

A webMethods Flow Steps

SEQUENCE
TheSEQUENCEstepformsacollectionofchildstepsthatexecutesequentially.Thisis usefulwhenyouwanttogroupasetofstepsasatargetforaBRANCHstep. Youcansetanexitconditionthatindicateswhetherthesequenceshouldexitprematurely and,ifso,underwhatcondition.Specifyoneofthefollowingexitconditions: Exit the sequence when a child step fails.Usethisconditionwhenyouwanttoensurethat allchildstepsarecompletedsuccessfully.Ifanychildstepfails,thesequenceends prematurelyandthesequencefails. Exit the sequence when a child step succeeds. Usethisconditionwhenyouwanttodefine asetofalternativeservices,sothatifonefails,anotherisattempted.Ifachildstep succeeds,thesequenceendsprematurelyandthesequencesucceeds. Exit the sequence after executing all child steps.Usethisconditionwhenyouwantto executeallofthechildstepsregardlessoftheiroutcome.Thesequencedoesnotend prematurely. The SEQUENCE step
First... child If exit condition is child If exit condition is child

Properties
TheSEQUENCEstephasthefollowingproperties. Property Description

Comments Optional.Specifiesadescriptivecommentforthisstep. Scope Optional.Specifiesthenameofadocument(IDataobject)inthepipelineto whichyouwanttorestrictthisstep.Ifyouwantthissteptohaveaccessto theentirepipeline,leavethispropertyblank. Optional.Specifiesthemaximumnumberofsecondsthatthisstepshould run.Ifthistimeelapsesbeforethestepcompletes,theserverwaitsforthe steptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty,typethe variablenamebetween%symbols.Forexample,%expiration%. Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeoutblank. Label Optional.(RequiredifyouareusingthisstepasatargetforaBRANCHor EXITstep.)Specifiesanameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank).

Timeout

394

webMethods Developer Users Guide Version 7.1.1

A webMethods Flow Steps

Property Exit on

Description Required.SpecifieswhentoexittheSEQUENCEstep. Specify this value... FAILURE To... Exitthesequencewhenachildstepfails.(Execution continueswiththenextflowstepintheflowservice.) TheSEQUENCEstepexecutesitschildstepsuntileither onefailsoruntilitexecutesallitschildsteps.Thisisthe default. Note: WhenaSEQUENCEstepexitsonfailure,the IntegrationServerrollsbackthepipelinecontents.That is,theIntegrationServerreturnsthepipelinetothestate itwasinbeforetheSEQUENCEstepexecuted. SUCCESS Exitthesequencewhenachildstepexecutes successfullyorafterallchildstepsfail.(Execution continueswiththenextflowstepintheflowservice.) Exitthesequenceafterallchildstepsexecute. TheSEQUENCEstepexecutesallofitschildsteps regardlessofwhethertheysucceedorfail.

DONE

Conditions that Will Cause the SEQUENCE Step to Fail

Thissectiondescribestheconditionsthatcausefailurebasedontheexitconditionforthe sequence. IfExit onissettoFAILURE,conditionsthatwillcauseafailureinclude: Oneofthechildstepsfails. TheSEQUENCEstepdoesnotcompletebeforethetimeoutperiodexpires. IfExit onissettoSUCCESS,conditionsthatwillcauseafailureinclude: Allthechildstepsfail. TheSEQUENCEstepdoesnotcompletebeforethetimeoutperiodexpires. IfExit onissettoDONE,conditionsthatwillcauseafailureinclude: TheSEQUENCEstepdoesnotcompletebeforethetimeoutperiodexpires.

webMethods Developer Users Guide Version 7.1.1

395

A webMethods Flow Steps

396

webMethods Developer Users Guide Version 7.1.1

Regular Expressions
398 398 398

What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

397

B Regular Expressions

What Is a Regular Expression?

AregularexpressionisapatternmatchingtechniqueusedextensivelyinUNIX environments.webMethodsDeveloperletsyouuseregularexpressionstospecify patternmatchingstringsforsomeofitsfunctions.Forexample,youcanusearegular expressiontospecifyanindex,aproperty,oramaskinawebMethodsQueryLanguage (WQL)statement.Youcanalsousearegularexpressiontospecifytheswitchvaluefora BRANCHstep. Tospecifyaregularexpression,youmustenclosetheexpressionbetween/symbols. Whentheserverencountersthissymbol,itknowstointerpretthecharactersbetween thesesymbolsasapatternmatchingstring(thatis,aregularexpression). Asimplepatternmatchingstringsuchas/string/matchesanyelementthatcontains string.So,forexample,theregularexpression/webMethods/wouldmatchallofthe followingstrings:
webMethods You use webMethods Integration Server to execute services Exchanging data with XML is easy using webMethods webMethods Integration Server

Important! Charactersinregularexpressionsarecasesensitive.

Using a Regular Expression in a Mask

Whenyouusearegularexpressionasamask,youuseparenthesistospecifywhich charactersyouwanttocollect.Forexample,theobjectreference:
doc.p[].text[/(.{30}).*/]

retainsthefirst30charactersineachmatchingelementanddiscardstherest.

Regular Expression Operators

FollowingaretheoperatorssupportedinthewebMethodsimplementationofregular expressions. Use this symbol . To Matchanysinglecharacterexceptanewline. Example doc.p[/web.ethods/].text Thisexamplewouldreturnanyparagraphcontainingthestringweb followedbyanysinglecharacterandthestringethods.Itwouldmatch bothwebMethodsandwebmethods.

398

webMethods Developer Users Guide Version 7.1.1

B Regular Expressions

Use this symbol ^

To Matchthebeginningofthestringorline. Example doc.p[/^webMethods/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsatthebeginningoftheelementoratthebeginningofany linewithinthatelement.

Matchtheendofthestringorline. Exampledoc.p[/webMethods$/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsattheendoftheparagraphelementorattheendofany linewithinthatelement.

Matchtheprecedingitemzeroormoretimes. Exampledoc.p[/part *555-A/].text Thisexamplewouldreturnanyparagraphcontainingthestringpart followedbyzeroormorespacesandthenthecharacters555A.

Matchtheprecedingitem1ormoretimes. Exampledoc.p[/part +555-A/].text Thisexamplewouldreturnanyparagraphcontainingthestringpart followedbyoneormorespacesandthenthecharacters555A.

Matchtheprecedingitem0or1times. Example doc.p[/part ?555-A/].text Thisexamplewouldreturnanyparagraphcontainingthestringpart followedbyzerooronespaceandthenthecharacters555A.

()

Whenusedinanindex,thesecharactersgroupanitemwithintheregular expression. Exampledoc.p[/part(,0)+May/].text Thisexamplewouldreturnanyparagraphcontainingthestringpart followedbyoneormoreoccurrencesofthecharacters,0andthenthe charactersMay. Whenusedinamask,theyspecifycharactersthatyouwanttoretain. Example doc.p[].text[(^.{25}).*] Thisexamplewouldkeepthefirst25characterswithineachparagraph anddiscardtherest.

webMethods Developer Users Guide Version 7.1.1

399

B Regular Expressions

Use this symbol {n}

To Matchtheprecedingitemexactlyntimes. Example doc.p[/^.{24}webmethods/].text Thisexamplewouldreturnanyparagraphinwhichtheword webmethodsstartedinthe25thcharacterpositionoftheparagraph.

{n,}

Matchtheprecedingitemnormoretimes. Example doc.p[/^.{10,}webmethods/].text Thisexamplewouldreturnanyparagraphinwhichtheword webmethodsappearedanywhereafterthe10thcharacterpositionofthe paragraph.Thatis,thisexamplewouldreturnaparagraphinwhichthe wordwebmethodsstartedinthe11thorlatercharacterpositionofthe paragraph.

{0,m}

Matchtheprecedingitemnoneoratmostmtimes. Exampledoc.p[/^.{0,4}webmethods/].text Thisexamplewouldreturnanyparagraphinwhichtheword webmethodsstartedinanyofthefirst5characterpositionsofthe paragraph.

{n,m}

Matchtheprecedingitematleastntimes,butnotmorethanmtimes. Exampledoc.p[/^.{1,4}webmethods/].text Thisexamplewouldreturnanyparagraphinwhichtheword webmethodsstartedincharacterposition2through5oftheparagraph.

Matchtheexpressionthatprecedesorfollowsthischaracter. Example doc.p[/webmethods|webMethods/].text Thisexamplewouldreturnanyparagraphthatcontainedeither webmethodsorwebMethods.

\b

Matchawordboundary. Exampledoc.p[/\bport\b/].text Thisexamplewouldreturnanyparagraphthatcontainedthewordport, butnotparagraphsthatcontainedthesecharactersaspartofalarger word,suchasimport,support,portsorported.

\B

Matchaboundarythatisnotawordboundary. Exampledoc.p[/\B555-A/].text Thisexamplewouldreturnanyparagraphthatcontainedthecharacters 555AaspartofalargerwordsuchasAZ555A,orDept555A,butnot 555Aalone.

400

webMethods Developer Users Guide Version 7.1.1

B Regular Expressions

Use this symbol \A

To Matchonlyatthebeginningofastring(equivalentto^). Exampledoc.p[/\AwebMethods/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsatthebeginningoftheelementoratthebeginningofany linewithinthatelement.

\Z

Matchonlyattheendofastring(orbeforeanewlineattheend). Example doc.p[/webMethods\Z/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsattheendoftheparagraphelementorattheendofany linewithinthatelement.

\n

Matchanewline. Exampledoc.p[/webMethods\n/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsfollowedbythenewlinecharacter.

\r

Matchacarriagereturn. Example doc.p[/webMethods\r/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsfollowedbyacarriagereturn.

\t

Matchatabcharacter. Exampledoc.p[/\twebMethods/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsprecededbyatabcharacter.

\f

Matchaformfeedcharacter. Exampledoc.p[/webMethods\f/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsfollowedbyaformfeedcharacter.

\d

Matchanydigit.Sameas[09]. Exampledoc.p[/part \d555-A/].text Thisexamplewouldreturnanyparagraphcontainingapartnumberthat startswithanydigit0through9,andisfollowedbythecharacters555A. Therefore,itwouldmatchpart1555AbutnotpartA555Aorpart #555A.

webMethods Developer Users Guide Version 7.1.1

401

B Regular Expressions

Use this symbol \D

To Matchanynondigit.Sameas[^09]. Example doc.p[/part \D555-A/].text Thisexamplewouldreturnanyparagraphcontainingapartnumberthat startswithanycharacterotherthan0through9,andisfollowedbythe characters555A.Therefore,itwouldmatchpartA555Aandpart#555 A,butnotpart1555A.

\w

Matchanywordcharacter.Sameas[09az_AZ]. Exampledoc.p[/part \w4555-A/].text Thisexamplewouldreturnanyparagraphcontainingapartnumberthat startswithaletterordigitandisfollowedbythecharacters555A. Therefore,itwouldmatchpartA555Aandpart1555A,butnotpart #555A.

\W

Matchanynonwordcharacter.Sameas[^09az_AZ]. Example doc.p[/part \W4555-A/].text Thisexamplewouldreturnanyparagraphcontainingapartnumberthat startswithacharacterotherthanaletterordigit,andisfollowedbythe characters555A.Therefore,itwouldmatchpart#555Aandpart555 A,butnotpart1555AorpartA555A.

\s

Matchanywhitespacecharacter.Sameas[\t\n\r\f]. Exampledoc.p[/\swebMethods/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethodsifitisprecededbyatabcharacter,anewlinecharacter,a carriagereturn,oraformfeedcharacter.

\S

Matchanynonwhitespacecharacter.Sameas[^\t\n\r\f]. Exampledoc.p[/\SwebMethods/].text Thisexamplewouldreturnanyparagraphcontainingthestring webMethods,ifthatstringisnotprecededbyatabcharacter,anewline character,acarriagereturn,oraformfeedcharacter.

\0

Matchanullstring. Exampledoc.p[/[^\0]/].text Thisexamplewouldreturnanyparagraphthatisnotempty(null).

\xnn

Matchanycharacterwiththehexadecimalvaluenn. Exampledoc.p[/\x1FwebMethods/].text ThisexamplewouldreturnanyparagraphcontainingtheASCIIunit separatorcharacter(1F)followedbythecharacterswebMethods.

402

webMethods Developer Users Guide Version 7.1.1

B Regular Expressions

Use this symbol []

To Matchanycharacterwithinthebrackets. Exampledoc.p[/part [023]555-A/].text Thisexamplewouldreturnanyparagraphcontainingapartnumberthat startswiththenumbers0,2,or3andisfollowedbythecharacters555A. Therefore,itwouldmatchpart0555Aandpart2555A,butnotpart 4555A. Thefollowingcharactershavespecialmeaningwhenusedwithin brackets: Use this char
^

To Excludecharactersfromthepattern. Exampledoc.p[/part [^023]555-A/].text Thisexamplewouldreturnanyparagraphcontaininga partnumberthatdoesnotstartwiththenumbers0,2, or3,butisfollowedbythecharacters555A.Therefore, itwouldmatchpart4555AandpartA555A,butnot part0555A.

Specifyarangeofallowedcharacters. Exampledoc.p[/part [A-M]555-A/].text Thisexamplewouldreturnanyparagraphcontaininga partnumberthatstartswithanyletterAthroughMand isfollowedbythecharacters555A.Therefore,itwould matchpartA555AandpartJ555A,butnotpart N555A.

webMethods Developer Users Guide Version 7.1.1

403

B Regular Expressions

404

webMethods Developer Users Guide Version 7.1.1

Supported Data Types

406 409

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

405

C Supported Data Types

Data Types
DataispassedinandoutofaservicethroughanIDataobject.AnIDataobjectisthe collectionofname/valuepairsonwhichaserviceoperates.AnIDataobjectcancontain anynumberofelementsofanyvalidJavaobjects,includingadditionalIDataobjectsand IDataCodableobjects. EachelementstoredinanIDataobjectcorrespondstoadatatype.Thefollowingtable identifiesthedatatypessupportedbyDeveloper. Data Type String Stringlist Stringtable Document Icon Description Stringofcharacters. AonedimensionalString array. AtwodimensionalString array. Adatastructurethatisa containerforother variables.Documentscan containvariablesofany otherdatatype.The contentsofadocument (IDataobject)arestoredas key/valuepairswherethe variablenameisthekey. Aonedimensionalarray ofISdocumenttypes (IData[]orValues[]). Adocumentwhose structureisdefinedbyan ISdocumenttype. Java Type java.lang.String java.lang.String[] java.lang.String[][] com.wm.data.IData com.wm.util.Values Formoreinformation,seethe webMethodsIntegrationServer JavaAPIReference.

Documentlist

com.wm.data.IData[] com.wm.util.Values[] com.wm.util.Table

Document reference

Referencetoanexistingobject whichimplementsthe com.wm.data.IDatainterfaceor areferencetoanexisting com.wm.util.Valuesobject. Referencetoanexistingobject whichimplementsthe com.wm.data.IDatainterfaceor areferencetoanexisting com.wm.util.Valuesobject.

Document referencelist

Adocumentlistwhose structureisdefinedbyan ISdocumenttype.

406

webMethods Developer Users Guide Version 7.1.1

C Supported Data Types

Data Type Object

Icon

Description Adatatypethatdoesnot fallintoanyofthedata typesdescribedinthe aboverows,andisnot declaredtobeoneofthe basicJavaclasses supportednativelyby IntegrationServer.This iconisusedforObjectsof unknowntype. AnarrayofObjectsof unknowntype.

Java Type Anysubclassofjava.lang.Object. Examplejava.util.InputStream

Objectlist

Anarrayofanysubclassof java.lang.Object. Examplejava.util.InputStream[]

Note: YoucanviewtheactualdatatypesrepresentedbyObjectorObjectlisticonsin builtinservicesbylookinguptheserviceinthewebMethodsIntegrationServerBuiltIn ServicesReference. Note: Developerdisplayssmallsymbolsnexttoavariableicontoindicatevalidation constraints.Developeruses toindicateanoptionalvariable.Developerusesthe symboltodenoteavariablewithacontentconstraint.Forinformationaboutapplying constraintstovariables,seeApplyingConstraintstoVariablesonpage 255.

Java Classes for Objects

YoucanfurtherdescribethecontentsofanObjectorObjectlistvariablebyapplyinga Javaclasstothevariable.WhenyouapplyasupportedJavaclasstoanObjectorObject listvariable,Developerchangestheiconforthevariable.ApplyingJavaclassestoObjects andObjectlistscanprovidethefollowingbenefits: Otherdeveloperscaneasilyseethetypesyourserviceexpectsasinputsandproduces asoutput. OtherdeveloperscaneasilyseethetypescontainedinanISdocumenttype. Youcaninputvaluesforthevariablewhentestinganddebugging. YoucanassignvaluestovariablesinthepipelineusingtheSet Value modifier.

Note: WhenyouinputvaluesforaconstrainedObjectduringtestingorwhen assigningavalueinthepipeline,Developervalidatesthedatatomakesureitisofthe correcttype.

webMethods Developer Users Guide Version 7.1.1

407

C Supported Data Types

ThefollowingtableidentifiestheJavaclassesyoucanapplytoObjectsandObjectlist variablesinDeveloper. Data Type boolean booleanlist byte Icon Description Trueorfalse. Aonedimensionalbooleanarray. Signedinteger.Thevaluemustbe greaterthanorequalto128but lessthanorequalto127. Aonedimensionalbytearray. Aonedimensionalbytearray. Asingleunicodecharacter. Aonedimensionalcharacter array. Dateandtime. Aonedimensionaldatearray. Doubleprecisionfloatingpoint number. Aonedimensionaldoublearray. Standardprecisionfloatingpoint number. Aonedimensionalfloatarray. Signedinteger.Thevaluemustbe greaterthanorequalto 2147483647butlessthanorequal to2147483647. Aonedimensionalintegerarray. Signedinteger.Thevaluemustbe greaterthanorequalto 9223372036854775808butless thanorequalto 9223372036854775807. Aonedimensionallongarray. Java Class java.lang.Boolean java.lang.Boolean[] java.lang.Byte

byte[] bytelist character characterlist date datelist double doublelist float floatlist integer

primitivetype java.lang.Byte[] java.lang.Character java.lang.Character[] java.util.Date java.util.Date[] java.lang.Double java.lang.Double[] java.lang.Float java.lang.Float[] java.lang.Integer

integerlist long

java.lang.Integer[] java.lang.Long

longlist

java.lang.Long[]

408

webMethods Developer Users Guide Version 7.1.1

C Supported Data Types

Data Type short

Icon

Description Signedinteger.Thevaluemustbe greaterthanorequalto32768but lessthanorequalto32767. Aonedimensionalshortarray.

Java Class java.lang.Short

shortlist

java.lang.Short[]

Note: ObjectandObjectlistvariablesconstrainedwithaJavaclassesshouldbelinked onlytootherObjectandObjectlistvariablesofthesameJavaclassorofunknown type.AlthoughDeveloperpermitsalinkbetweenconstrainedObjectsofdifferent Javaclasses,theruntimebehaviorisundefined.Formoreinformationabout specifyingJavaclassesforObjects,seeConsiderationsforObjectConstraintson page 257.

How webMethods Developer Supports Tables

WiththeexceptionofStringtable,Developerdoesnotprovideaseparatedatatypefor tables.However,tablescanappearasdocumentlistsorObjects.Tablesthatareinstances ofcom.wm.util.TableappearasdocumentlistsinwebMethodsDeveloper.Thesetables canbeusedasdocumentlistsinflowservices.ServicesintheWmDBpackageusetables thatareinstancesofwm.com.util.Table. TablescanalsobedeclaredasObjects.Objectsoruserdefinedtablelikeobjectsthatdo notimplementthecom.wm.util.pluggable.WMIDataListinterfaceappearasObjectsof unknowntypeinwebMethodsDeveloper.

Default Pipeline Rules for Linking to and from Array Variables

Whenyoucreatelinksbetweenscalarandarrayvariables,youcanspecifywhichelement ofthearrayvariableyouwanttolinktoorfrom.Scalarvariablesarethosethatholda singlevalue,suchasString,ISdocumenttype,andObject.Arrayvariablesarethosethat holdmultiplevalues,suchasStringlist,Stringtable,documentlist,andObjectlist.For example,youcanlinkaStringtothesecondelementofaStringlist. Ifyoudonotspecifywhichelementinthearrayvariablethatyouwanttolinktoorfrom, DeveloperusesthedefaultrulesonthePipelinetabtodeterminethevalueofthetarget variable.Thefollowingtableidentifiesthedefaultpipelinerulesforlinkingtoandfrom arrayvariables.

webMethods Developer Users Guide Version 7.1.1

409

C Supported Data Types

If you link Ascalar variable

To Anarrayvariablethatis empty(thevariabledoesnot haveadefinedlength)

Then Thelinkdefinesthelengthofthe arrayvariable;thatis,itcontains oneelementandhaslengthofone. Thefirst(andonly)elementinthe arrayisassignedthevalueofthe scalarvariable.

value If you link Ascalar variable

[empty] To Anarrayvariablewitha definedlength

value Then Thelengthofthearrayispreserved andeachelementofthearrayis assignedthevalueofthescalar variable.

value

X Y Z To Ascalarvariable

value value value Then Thescalarvariableisassignedthe firstelementinthearray.

If you link Anarray variable

X Y Z

[empty]

410

webMethods Developer Users Guide Version 7.1.1

C Supported Data Types

If you link Anarray variable

To Anarrayvariablethatdoes nothaveadefinedlength

Then Thelinkdefinesthelengthofthe targetarrayvariable;thatis,itwill bethesamelengthasthesource arrayvariable.Theelementsinthe targetarrayvariableareassigned thevaluesofthecorresponding elementsinthesourcearray variable.

X Y Z If you link Anarray variable

[empty]

X Y Z Then Thelengthofthesourcearray variablemustequalthelengthofthe targetarrayvariable.Ifthelengths donotmatch,thelinkwillnot occur.Ifthelengthsareequal,the elementsinthetargetarrayvariable areassignedthevaluesofthe correspondingelementsinthe sourcearrayvariable.

To Anarrayvariablethathasa definedlength

X Y Z

A B C

X Y Z Nolinkoccurs.

V W X Y Z

A B C

Note: Asourcevariablethatisthechildofadocumentlististreatedlikeanarray becausethereisonevalueofthesourcevariableforeachdocumentinthedocument list.Forexample:

webMethods Developer Users Guide Version 7.1.1

411

C Supported Data Types

If you link... DocumentLis String

To... StringList

Where the value of DocumentList1 is... DocumentLis DocumentList1 a DocumentList1 String b DocumentList1 String c String

Then the value of StringList1 is StringList a b c

412

webMethods Developer Users Guide Version 7.1.1

Conditional Expressions
414 415 418 424 425 428

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

413

D Conditional Expressions

Overview
webMethodsIntegrationServerprovidessyntaxandoperatorsthatyoucanusetocreate expressionsforusewiththeBRANCHstep,pipelinemapping,andtriggers. InaBRANCHstep,youcanuseanexpressiontodeterminethechildstepthat webMethodsIntegrationServerexecutes.Atruntime,theIntegrationServerexecutes thefirstchildstepwhoseconditionalexpressionevaluatestotrue.Formore informationabouttheBRANCHstep,seeTheBRANCHSteponpage 160 Inpipelinemapping,youcanplaceaconditiononthelinkbetweenvariables.Atrun time,webMethodsIntegrationServeronlyexecutesthelinkiftheassignedcondition evaluatestotrue.Formoreinformationaboutapplyingconditionstolinksbetween variables,seeApplyingConditionstoLinksBetweenVariablesonpage 204. ForBroker/localtriggers,youcanfurtherrefineasubscriptionbycreatingfiltersfor thepublishabledocumenttypes.Afilterspecifiescriteriaforthecontentsofa document.Atruntime,theBrokerorIntegrationServerappliesthefiltertothe document.TheBrokerorIntegrationServerwillrouteorprocessthedocumentonly ifthedocumentmeetsthefiltercriteria.Formoreinformation,seethePublish SubscribeDevelopersGuide. Important! Ifmultipleconditionsinthetriggerspecifythesamepublishable documenttype,thefilterappliedtothepublishabledocumenttypemustbethe sameineachcondition. ForJMStriggers,youcancreatelocalfilterstofurtherlimitthemessagesaJMS triggerprocesses.Afilterspecifiescriteriaforthecontentsofthemessagebody. IntegrationServerappliesalocalfiltertothemessageaftertheJMStriggerreceives themessagefromtheJMSprovider.Ifthemessagemeetsthefiltercriteria,Integration Serverexecutesthetriggerservicespecifiedintheroutingrule. Whenyouwriteexpressionsandfilters,keepthefollowingpointsinmind: Operators,variablenames,andstringsarecasesensitive. Whitespacebetweenthetokensofanexpressionisignored. SomesyntaxthatisvalidontheIntegrationServerisnotvalidontheBroker.Ifthe syntaxisvalidforaBroker,theIntegrationServersavesthefilterwiththe subscriptionontheBroker.Ifthesyntaxisnotvalid,theIntegrationServersavesthe subscriptionwithoutthefilterontheBroker.Subscriptionsandfiltersarealways savedontheIntegrationServer. Foralistandanexampleofsyntaxthatpreventsafilterfrombeingsavedonthe Broker,seeRulesforUseofExpressionSyntaxwiththeBrokeronpage 428.

414

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Syntax
Whenyoucreateanexpression,youneedtodeterminewhichvaluestoincludeinthe expression.Valuescanberepresentedasvariablenames,regularexpressions,numbers, andstrings.Thefollowingtableidentifiesthetypesofvaluesyoucanuseinan expressionandthesyntaxforeachvaluetype. Value Type Regular Expression Syntax /regularExpression/ Description Patternmatchingstring.Usethefollowing syntaxforpatternmatchingofvariablevalues: variableName=/regularExpression/ Formoreinformationaboutregularexpressions, seeAppendix B,RegularExpressions. Example
sku = /^WM[0-9]+/

Explanation Evaluatestotrueifthe skuvariablehasavalue thatstartswithWM andisfollowedbyone ormoredigits(WM001, WM95157)

Variable

variableName OR %variableName%

Variablename.Forinformationabouthowtouse thissyntaxtoaddresschildrenofothervariables orelementsofarrayvariables,seeAddressing Variablesonpage 425. Example

price

Explanation Valueoftheprice variable ValueofthepostalCode variableintheaddress document Valueofthefirst elementinthepoItems array

%address/postalCode%

%poItems[0]%

webMethods Developer Users Guide Version 7.1.1

415

D Conditional Expressions

Value Type String

Syntax string OR string

Description Literalstring.Usethisvaluetypetocomparethe valueofavariabletoastring.

Example
Favorite Customer

Explanation Valueistheliteralstring FavoriteCustomer Valueistheliteralstring FavoriteCustomer

Favorite Customer

Note: Stringsnotenclosedinquotes(or)are interpretedasvariablenames. Number number Number.Thefollowingexamplesindicatethe acceptednumberformats: Examples

-10, 5, 100 5.0, 6.02

Explanation Integers Floatingpointnumber (java.lang.Double) Scientificnotation

6.345e+4

Null

$null

Variableisnullormissing.Typicallycompared withavariablenametodetermineifthevariable isnullormissingfromtheinputdata. Example

%quantity% = $null

Explanation Evaluatestotrueifthe quantityvariableis missingfromtheinput dataorisnull

416

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Comparing Java Objects to Constants

IfyouwanttocreateaconditionalexpressionthatcomparesaconstrainedJavaObjectto aconstantvalue,youmustusethefollowingsyntaxtorepresenttheconstantvalue: If the object is constrained as type... Boolean Use this syntax... trueorfalse Example:%myBoolean%=="true" Thestringconstantintheexpressioniscaseinsensitive.For example,theexpressions%myBoolean%=="true"and %myBoolean%=="tRUe"areequivalent. Byte xx Example:10(for0X0A) Character a Example:C Double xxxxxx.xorxxxxxxorxxxxxx Example:123456.0,123456,123456 Float xxxx.xorxxxx.x Example:1234.1,1234.1 Integer xxxxxorxxxxx Example:12345,12345 Long xxxxxxorxxxxxx Example:123456or123456 Short xxxorxxx Example:123or123 Date yyyyMMddHH:mm:sstimezone Example:2002062500:00:00EDT

webMethods Developer Users Guide Version 7.1.1

417

D Conditional Expressions

Checking for Variable Existence

Sometimesyoumightwanttocreateanexpressionthatchecksonlyfortheexistenceofa variableorcheckstoseewhetheravariableisnull.Thefollowingtabledescribesthe syntaxusedtocheckforvariableexistence. To see if Variable exists Use this syntax variableName Description Evaluatestotrueifthespecifiedvariableexistsand hasanonnullvalue. This example...
customerID

Evaluates to true if... ThecustomerIDvariableexistsand isnotnull.

Variable doesnot exist

!variableName

Evaluatestotrueifthespecifiedvariabledoesnot existorisnull. This example...

!quantity

Evaluates to true if... Thequantityvariabledoesnot existorisnull. Thecolorvariabledoesnotexistor isnullandthesizevariabledoes notexistorisnull.

!color & !size

Operators
Expressionscanincluderelationalandlogicaloperators.Relationaloperatorsareusedto comparevaluestoeachother.Logicaloperatorsareusedtocombinemultipleexpressions intoasinglecondition.

Relational Operators
Youcanuserelationaloperatorstocomparethevalueoftwofieldsoryoucancompare thevalueofafieldwithaconstant.TheIntegrationServerprovidestwotypesof relationaloperators:standardandlexical. Standardrelationaloperatorscanbeusedinexpressionsandfilterstocomparethe contentsoffields(variables)withothervariablesorconstants. Lexicalrelationaloperatorscanbeusedtocomparethecontentsoffields(variables) withstringvaluesinBroker/localtriggerfilters. Relationaloperatorsaresometimescalledcomparisonoperators.

418

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Note: Youcanalsousestandardrelationaloperatorstocomparestringvalues. However,filtersthatusestandardrelationaloperatorstocomparestringvalueswill notbesavedwiththetriggersubscriptionontheBroker.Ifthesubscriptionfilter residesonlyontheIntegrationServer,theBrokerautomaticallyplacesthedocument inthesubscribersqueue.TheBrokerdoesnotevaluatethefilterforthedocument. TheBrokerroutesallofdocumentstothesubscriber,creatinggreaternetworktraffic betweentheBrokerandtheIntegrationServerandrequiringmoreprocessingbythe IntegrationServer.

Standard Relational Operators

Youcanusethestandardrelationaloperatorstocomparethecontentsofavariablewith anytypeofvalue(numerical,string,Boolean,dates,etc.)oranothervariable. Whencomparingstringsusingthestandardoperators,theIntegrationServerusesa binarycodepointcomparisonalgorithm.Inthisalgorithm,theIntegrationServer compareseachbyteinthefirststringwitheachbyteinthesecondstringtodetermine whichstringisnumericallygreater.Forexample,Ahasavalueof65andahasa valueof97,soaisgreaterthanA. Keepthefollowingpointsinmindwhenusingstandardrelationaloperatorstocompare strings: TheIntegrationServerconsidersAtobethelowestletterandZtobethehighest(for example,A<B,A<Z,B>A,Z>A). TheIntegrationServerconsiderslowercaseletterstobegreaterthanthematching uppercaseletter(forexample,a>A,A<a,a<B,c>A). Thefollowingtableidentifiesthestandardrelationaloperatorsyoucanusein expressionsandfilters. Operator = Syntax a=b Description Equalto. This example...
customerID = "webMethods"

Evaluates to true if... ThevalueofthecustomerId variableiswebMethods. Evaluates to true if.. Thevalueoftheskuvariableis WM001.

==

a==b

Equalto. This example...

sku == "WM001"

webMethods Developer Users Guide Version 7.1.1

419

D Conditional Expressions

Operator !=

Syntax a!=b

Description Notequalto. This example...

quantity != 0

Evaluates to true if.. Thevalueofthequantityvariable doesnotequal0(zero). Evaluates to true if.. Thevalueofthestatevariabledoes notequalME(Maine). Evaluates to true if.. Thevalueofthepricevariableis greaterthan100. ThevalueofthecompanyID variableisgreaterthanAcme. Evaluates to true if.. ThevalueofthetotalPricevariable isgreaterthanorequalto100. ThevalueofthecompanyID variableisgreaterthanorequalto Acme. Evaluates to true if.. Thevalueofthequantityvariable islessthan5. ThevalueofthecompanyID variableislessthanAcme.

<>

a<>b

Notequalto. This example...

state <> 'ME'

>

a>b

Greaterthan. This example...

price > 100

%companyID% > "Acme"

>=

a>=b

Greaterthanorequalto. This example...

%totalPrice% >= 100

companyID >= "Acme"

<

a<b

Lessthan. This example...

quantity < 5

companyID < "Acme"

420

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Operator <=

Syntax a<=b

Description Lessthanorequalto. This example...

unitPrice <= 100

Evaluates to true if.. ThevalueoftheunitPricevariable islessthanorequalto100. ThevalueofthecompanyID variableislessthanorequalto Acme.

companyID <= "Acme"

Lexical Relational Operators

Youcanusethelexicalrelationaloperatorstocreatefiltersthatcomparestringvalues. Keepthefollowingpointsinmindwhenusingthelexicaloperators: Whenevaluatingfiltersthatcontainlexicaloperators,theIntegrationServerusesthe localecollatingsequencespecifiedontheBrokertocomparethevaluesofthestrings. ThebehavioroflexicaloperatorsdependsonwhetheralocaleissetfortheBroker.If nolocaleisspecified,thelexicalrelationaloperatorsbehavelikethestandard relationaloperators. Note: Tosetthefiltercollationlocale,usetheBrokeruserinterfacetoselectthe BrokerServerforwhichyouwanttochangethelocale.OntheBrokerServer Informationscreen,selectChange Broker Server Filter Collation Locale. Then,onthe ChangeFilterCollationLocalescreen,intheNew Localelist,selectthelocaleyou wanttouse.RestarttheBrokerServerforthechangetotakeeffect. Ifyouusealexicaloperatortocomparestringsinanexpression(suchasina BRANCHsteporinapipelinelink),theIntegrationServertreatsthelexicaloperators asiftheywerestandardrelationaloperators. Ifyouusealexicaloperatortocompareavaluethatisnotastringwithanotherstring value,theIntegrationServertreatsthenonstringvalueasanemptystring(thatis,). Forexample,intheexpression(%myInt% L_EQUALS ""),the%myInt%variableis declaredtobeoftypeinteger.Thisexpressionalwaysevaluatestotruebecause %myInt%containsanintegervaluethattheIntegrationServertreatsasanemptystring ()whenitevaluatestheexpression. Filtersthatuselexicalrelationaloperatorstocomparestringvalueswillbesavedwith thetriggersubscriptionontheBroker.Filtersthatusestandardrelationaloperatorsto comparestringvalueswillnotbesavedontheBroker. WhenyouviewfiltersontheBrokeruserinterface,alexicaloperatorappearsasits equivalentstandardoperator.Forexample,theexpression%myString% L_EQUALS "abc"appearsasmyString=="abc". Thefollowingtabledescribesthelexicaloperatorsthatyoucanuseinfilters.

webMethods Developer Users Guide Version 7.1.1

421

D Conditional Expressions

Operator
L_EQUALS

Description Lexicalequalto. This example...

%myString% L_EQUALS "abc"

Evaluates to true if.. Thevalueofthe myStringvariableis abc. Evaluates to true if.. Thevalueofthe myStringvariableis notabc. Evaluates to true if.. Thevalueofthe myStringvariableis lessthanabc. Evaluates to true if.. Thevalueofthe myStringvariableis lessthanorequalto abc. Evaluates to true if.. Thevalueofthe myStringvariableis greaterthanabc. Evaluates to true if.. Thevalueofthe myStringvariableis greaterthanorequal toabc.

L_NOT_EQUALS

Lexicalnotequalto. This example...

%myString% L_NOT_EQUALS "abc"

L_LESS_THAN

Lexicallessthan. This example...

%myString% L_LESS_THAN "abc"

L_LESS_OR_EQUAL

Lexicallessthanorequalto. This example...

%myString% L_LESS_OR_EQUAL "abc"

L_GREATER_THAN

Lexicalgreaterthan. This example...

%myString% L_GREATER_THAN "abc"

L_GREATER_OR_EQUAL

Lexicalgreaterthanorequalto. This example...

%myString% L_GREATER_OR_EQUAL "abc"

422

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Logical Operators
Youcanusethefollowinglogicaloperatorsinexpressionstocreateconditionsconsisting ofmorethanoneexpression: Operator ! Syntax !expr Description Negatesthenextexpression. This example...
! (%sku% = "WM001")

Evaluates to true if.. Thevalueoftheskuvariableis notequaltoWM001. Evaluates to true if.. Thecolorvariableisnotequal toblue. Evaluates to true if.. Thevalueofthecolorvariable isblueorred. Evaluates to true if.. ThevalueofthetotalPrice variableisgreaterthan1000or thevalueofthecustomerID variableequalsFavorite Customer. Evaluates to true if.. ThevalueofthecreditCardNum variableisnullormissingorif thevalueofthecardExpireDate variableisnullormissingorif thevalueofthecardExpireDate variableislessthanorequalto thevalueoftheorderDate variable.

not

notexpr

Negatesthenextexpression. This example...

not (color = "blue")

expr|expr

Logical*OR.Trueifeitheroftheexpressionsistrue. This example...

%color% = "blue" | %color% = "red"

||

expr||expr

LogicalOR.Trueifeitheroftheexpressionsistrue. This example...

totalPrice > 1000 || customerID = 'Favorite Customer'

or

exprorexpr

LogicalOR.Trueifeitheroftheexpressionsistrue. This example...

creditCardNum = $null or cardExpireDate = $null or cardExpireDate <= orderDate

webMethods Developer Users Guide Version 7.1.1

423

D Conditional Expressions

Operator &

Syntax expr&expr

Description LogicalAND.Bothexpressionsmustevaluatetotrueforthe entireconditiontobetrue. This example...

%customerID% = 'Favorite Customer' & %sku% = 'WM001'

Evaluates to true if.. ThevalueofthecustomerID variableisFavoriteCustomer andthevalueofthesku variableisWM001.

&&

expr&& expr

LogicalAND.Bothexpressionsmustevaluatetotrueforthe entireconditiontobetrue. This example...

quantity >= 20 && totalPrice >= 100

Evaluates to true if.. Thevalueofthequantity variableisgreaterthanor equalto20andthevalueofthe totalPricevariableisgreater thanorequalto100.

and

exprand expr

LogicalAND.Bothexpressionsmustevaluatetotrueforthe entireconditiontobetrue. This example...

!color and !size

Evaluates to true if.. Thecolorvariabledoesnot existintheinputorisnulland thesizevariabledoesnotexist intheinputorisnull.

Precedence
webMethodsIntegrationServerevaluatesexpressionsinaconditionaccordingtothe precedenceleveloftheoperatorsintheexpressions. Thefollowingtableidentifiestheprecedencelevelofeachoperatoryoucanuseinan expression. Precedence Level 1 2 3 4 5 Operators ( ) not,! =,==,!=,<>,>,>=,<,<= and,&,&& or,|,||

424

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Note: Tooverridetheorderinwhichexpressionsinaconditionareevaluated,enclose theoperationsyouwantevaluatedfirstinparentheses.webMethodsIntegration Serverevaluatesexpressionscontainedinparenthesesfirst.

Addressing Variables
Inanexpression,youcanrefertothevaluesofvariablesthatarechildrenofother variablesandrefertothevaluesofelementsinanarrayvariable.Toaddresschildrenof variablesoranelementinanarray,youneedtouseadirectorylikenotationtodescribe thepositionofthevalue. Use this notation variableName To Addressavariable. Example:state Variablestate. variableName/childVariableName Addressthechildvariableofa variable(suchasafieldina document). Example:%buyerInfo/state% VariablestatewithinISdocumenttype buyerInfo. arrayVariableName[index] Addressanelementinanarray. Example:orderItems[0] Valueofthefirstelementinthe orderItemsarray. arrayVariableName[rowIndex][columnIndex] Addressanelementina twodimensionalarray(Stringtable). Example: dictionary[1][2] Valueoftheelementlocatedinthe thirdcolumnofthesecondrowinthe dictionaryarray.

webMethods Developer Users Guide Version 7.1.1

425

D Conditional Expressions

Use this notation duplicateVariableName(index)

To Addressanoccurrenceofavariable wheretherearemultiplevariables withthesamenameinthedocument orpipeline.Theindexiszerobased. Example:address(1) Valueofthesecondvariablenamed address.

%variableWithSpecialCharacters%

Addressavariablewhosename containsspecialcharacters.Variables thatcontainspecialcharactersmust beenclosedinquotationmarks. Example:%address(work)% Valueofthevariablenamed address(work). Formoreinformation,see AddressingVariablesthatContain SpecialCharactersbelow.

Notes: Toviewthepathtoavariableinthepipeline,restthemousepointeroverthevariable name.Developerdisplaysthevariablepathinatooltip. Tocopythepathtoavariableinapipeline,selectthevariable,rightclick,andselect Copy. Youcanenclosevariablenamesin%,forexample%buyerInfo/state%.Ifthevariable nameincludesspecialcharacters,youmustenclosethepathtothevariablein% (percent)symbolsandenclosethevariablenamein(quotationmarks).Formore informationaboutusingvariablesasvaluesinexpressions,seeSyntaxonpage 415.

Addressing Variables that Contain Special Characters

Ifavariablenamecontainsanyofthespecialcharacterslistedinbelow,youneedtouse thefollowingnotationtoaddressthevariable: Enclosethepathtothevariableandthevariablenamein%(percentsymbols). Enclosethevariablenamethatcontainsspecialcharactersin(quotationmarks).

426

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

Followingaresomeexamplesofhowtoaddressvariablesthatcontainspecialcharacters. Type...
%Date/Time% %purchaseOrder/"Date/Time%

To... AddressavariablenamedDate/Time. AddressavariablenamedDate/Timeinthe documentvariablepurchaseOrder. Note: IfyoudidnotencloseDate/Timein quotationmarks,andinsteadhad %purchaseOrder/Date/Time%or %purchaseOrder/Date/Time%,theexpression wouldaddressavariablenamedTimeina documentnamedDatethatwascontainedina documentnamedpurchaseOrder.

%address(work)/phone(cell)% %Date\\Time%

Addressavariablenamedphone(cell)inthe documentvariableaddress(work). AddressavariablenamedDate\Time.

Typing Special Characters in Expressions

Youentermostofthespecialcharactersinanexpressionjustasyouwouldenterthem whencreatingthevariablename.However,forthreeofthespecialcharacters(the backslash,percentsymbol,andquotationmarks),youneedtouseacombinationofkeys. Thefollowingtableidentifiesthespecialcharactersforvariablenamesandanykey sequencesthatyouneedtousetoenteravariablenamewiththatcharacterinan expression. Character \ [ ] ( ) % " / Character Name backslash openingbracket closingbracket openingparenthesis closingparenthesis percent quotationmarks slashmark(forward) Important! Whenyouusevariablenameswithspecialcharactersinexpressionsor filters,youmustenclosethevariablenamein(quotationmarks). \% \ Special sequence \\

webMethods Developer Users Guide Version 7.1.1

427

D Conditional Expressions

Rules for Use of Expression Syntax with the Broker

WhenyoucreatefiltersfordocumentsinBroker/localtriggerconditions,keepinmind thatsomesyntaxthatisvalidonIntegrationServerisnotvalidonBroker.Whenyousave aBroker/localtrigger,IntegrationServerandBrokerevaluatethefiltertomakesurethat itusespropersyntax.IfthesyntaxisvalidonBroker,Brokersavesthesubscriptionand thefilter.IfthesyntaxisinvalidonBroker,IntegrationServerautomaticallyremovesthe filterbeforetheBrokersavesthesubscription.ThefilterwillonlybesavedonIntegration Server. Note: Brokersavesasmuchofafilteraspossiblewiththesubscription.Forexample, supposethatafilterconsistsofmorethanoneexpression,andonlyoneofthe expressionscontainssyntaxBrokerconsidersinvalid.Brokersavestheexpressionsit considersvalidbutdoesnotsavetheexpressioncontaininginvalidsyntax. (IntegrationServersavesalltheexpressions.) KeepthefollowingpointsinmindwhenwritingfiltersforBroker/localtriggers: Expressionsthatspecifyfieldnamesthatcontainsyntax,characters,symbols,or wordstheBrokerconsidersrestrictedorreservedwillnotbesavedontheBroker. Allexpressionsmustcontainarelational(comparison)operator. Uselexicalrelationaloperators(suchasL_EQUALS,L_LESS_THAN)tocomparefieldsof typeString. Usestandardrelationaloperators(suchas=,==,!=,<,>,<=and>=)tocomparefields thatarenotoftypeString. Usethe=,==,<>,or!=operatorstocompareavaluewithanObjectconstrainedasa Boolean. ThefollowingtableidentifiessyntaxthattheBrokerconsidersinvalid.Expressionswith thissyntaxwillbesavedontheIntegrationServerbutnotontheBroker. Tip! YoucanusetheBrokeruserinterfacetoviewthefilters(expressions)savedwitha subscription.IftheexpressiondoesnotappearwiththesubscriptionontheBroker, thentheexpressioncontainsinvalidsyntax.

428

webMethods Developer Users Guide Version 7.1.1

D Conditional Expressions

The Broker considers expressions invalid when they contain.... Fieldnameswithsyntax,characters, symbols,orwordstheBrokerconsiders restrictedorreserved

Examples
eventtype L_EQUALS addEmployee tax% < 5

Note: AlthoughtheBrokerconsidersa fieldnamethatcontainsthe%symbolto beinvalid,youcanusethe%symbolto enclosefieldnamesintheexpression.

"fieldName" "!fieldName" %myString% < "yourString"

Nocomparisonoperators Astandardrelationaloperatorto comparefieldsoftypeString Alexicalrelationaloperatortocompare fieldsthatarenotoftypeString AfieldoftypeStringcomparedwitha numericvalue Operatorsotherthan=,==,!=,or<>to compareanObjectconstrainedasa Booleanwithavalue AnObjectconstrainedasaBoolean comparedwithafieldoftypeString

%price% L_LESS_THAN 50

"stringName" > 12

myBoolean <= "true"

myBoolean = "stringFieldName"

Note: ExpressionsthatcheckanObject constrainedasaBooleanforatrueorfalse valueshouldincludetrueorfalseas partofthefilter.Thestringconstantinthe expression(trueorfalse)iscase insensitive.

%fieldName% = $null stringList[1] L_EQUALS "a" fieldName = /^(a|b)\1$/

A$nulltoken Areferencetoanarrayfield Regularexpressionsthatcontainback references Regularexpressionsthatusequantifiers otherthan+,?,and* Regularexpressionsthatuseextended metacharacters

/a{1}/ /a{1,5}/
fieldName = /\w/

webMethods Developer Users Guide Version 7.1.1

429

D Conditional Expressions

430

webMethods Developer Users Guide Version 7.1.1

jcode tags
432 432

jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

431

E jcode tags

jcode Template
Thefollowingcodeprovidesatemplatedescribingthetags(highlighted)thatthejcode utilityusestoidentifycodesegmentsinaJavasourcefile.
package Interface1; /** * This is an example of an empty Java source code file, * properly annotated for use with the jcode utility. */ import com.wm.app.b2b.server.Service; import com.wm.app.b2b.server.ServiceException; import com.wm.data.IData; import com.wm.data.IDataCursor; // --- <<IS-START-IMPORTS>> --// --- <<IS-END-IMPORTS>> --public class Interface0 { public static void Service1 (IData pipeline) throws ServiceException { // --- <<IS-START(Service1)>> --// --- <<IS-END>> --return; } public static void Service2 (IData pipeline) throws ServiceException { // --- <<IS-START(Service2)>> --// --- <<IS-END>> --return; } // --- <<IS-START-SHARED>> --// --- <<IS-END-SHARED>> --}

jcode Example
ThefollowingisacompleteexampleofproperlycommentedJavasourcecode.

Sample CodeIData
Thefollowingisanexampleofaclasswhoseservices(methods)takeIDataobjectsas input.
package recording; /** * This is an example of Java source code properly annotated * for use with the IS jcode utility. Note that, unless * noted otherwise, all comments will be stripped out of this * file during the process of fragmenting the code. */

432

webMethods Developer Users Guide Version 7.1.1

E jcode tags

/** * == IMPORTS == * All your imports should be wrapped with the START-IMPORTS * and END-IMPORTS tags. */ // --- <<IS-START-IMPORTS>> --import com.wm.app.b2b.server.Service; import com.wm.app.b2b.server.ServiceException; import com.wm.data.IData; import com.wm.data.IDataCursor; import com.wm.data.IDataUtil; import java.util.*; // --- <<IS-END-IMPORTS>> --/** * == CLASS NAMING == * This class contains the definition of all the Java services * within the recording.accounts interface (note the recording * package declaration up top). Note that each service is * defined by a method with the same name. */ public class accounts { /** * == INDIVIDUAL SERVICES == * The createAccount service. This service expects three * parameters -- a string ("name"), a string array ("references"), * and a document type. It returns two strings ("message" and "id"). * * Note the special tags delimiting the start and end of the * service. The two lines immediately before start tag and after * the end tags are mandatory. * * Also note the use of comments to establish a signature for the * service. Each signature line has the following format: * * [direction] type:dimension:option name * * direction: "i" (input) or "o" (output) * type: * field (corresponds to instances of java.lang.String) * document type (corresponds to instances of com.wm.data.IData) * object (corresponds to instances of any other class) * option: * required (this parameter is mandatory) * optional (this parameter is optional) * name: the name of the parameter * * To indicate nesting, use a single "-" at the beginning of * each line for each level of nesting. */ public static void createAccount (IData pipeline) throws ServiceException { // --- <<IS-START(createAccount)>> --// [i] field:0:required name // [i] field:1:required references // [i] record:0:required data // [i] - field:1:required address // [i] - field:1:required phone // [o] field:1:required message

webMethods Developer Users Guide Version 7.1.1

433

E jcode tags

// [o] field:1:required id IDataCursor idc = pipeline.getCursor(); String name = IDataUtil.getString(idc, "name"); String [] refs = IDataUtil.getStringArray(idc, "references"); IData data = IDataUtil.getIData(idc, "data"); // Do something with the information here. Note that this // comment inside the service body is the only one that won't // get discarded when fragmenting the service (i.e., it will // show up in Developer.) idc.last(); idc.insertAfter ("message", "createAccount not fully implemented"); idc.insertAfter ("id", "00000000"); idc.destroy(); // --- <<IS-END>> --return; } /** * == COMPLEX SIGNATURES == * The getAccount service. This service takes a single string * "id", and returns a complex structure representing the * account information. Note the use of the helper functions * (defined below). */ public static void getAccount (IData pipeline) throws ServiceException { // --- <<IS-START(getAccount)>> --// [i] field:0:required id // [o] record:1:required account // [o] - field:0:required name // [o] - field:1:required refs // [o] - record:0:required contact // [o] -- field:0:required address // [o] -- field:0:required phone IDataCursor idc = pipeline.getCursor(); if(idc.first("id")) { try { String id = IDataUtil.getString(idc); IData data = getAccountInformation(id); idc.last(); idc.insertAfter ("account", data); } catch (Exception e) { throw new ServiceException(e.toString()); } } idc.destroy(); // --- <<IS-END>> --} /** * == SHARED SOURCE == * This is where the shared code lives. This includes both * global data structures and non-public functions that aren't * exposed as Services. Note the tags delimiting the start * and end of the shared code section. */

434

webMethods Developer Users Guide Version 7.1.1

E jcode tags

// --- <<IS-START-SHARED>> --private static Vector accounts = new Vector(); private static IData getAccountInformation (String id) { throw new RuntimeException ("this service is not implemented yet"); } // --- <<IS-END-SHARED>> --}

webMethods Developer Users Guide Version 7.1.1

435

E jcode tags

436

webMethods Developer Users Guide Version 7.1.1

Validation Content Constraints

438 438 448

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

437

F Validation Content Constraints

Overview
YoucanapplycontentconstraintstovariablesintheISdocumenttypes,specifications,or servicesignaturesthatyouwanttouseasblueprintsindatavalidation.Content constraintsdescribethedataavariablecancontain.Atvalidationtime,ifthevariable valuedoesnotconformtothecontentconstraintsappliedtothevariable,thevalidation engineconsidersthevaluetobeinvalid.Formoreinformationaboutvalidation,see Chapter 10,PerformingDataValidation. Whenapplyingcontentconstraintstovariables,youcandothefollowing: Select a content type.Acontenttypespecifiesthetypeofdataforthevariablevalue, suchasstring,integer,boolean,ordate.Acontenttypecorrespondstoasimpletype definitioninaschema. Set constraining facets.Constrainingfacetsrestrictthecontenttype,whichinturn, restrictthevalueofthevariabletowhichthecontenttypeisapplied.Eachcontent typehasasetofconstrainingfacets.Forexample,youcansetalengthrestrictionfora stringcontenttype,oramaximumvaluerestrictionforanintegercontenttype. Forexample,foraStringvariablenameditemQuantity,youmightspecifyacontenttype thatrequiresthevariablevaluetobeaninteger.Youcouldthensetconstrainingfacets thatlimitthecontentofitemQuantitytoavaluebetween1and100. Thecontenttypesandconstrainingfacetsdescribedinthisappendixcorrespondtothe builtindatatypesandconstrainingfacetsinXMLSchema.TheWorldWideWeb Consortium(W3C)definesthebuiltindatatypesandconstrainingfacetsinthe specificationXMLSchemaPart2:Datatypes(http://www.w3c.org/TR/xmlschema2).

Content Types
ThefollowingtableidentifiesthecontenttypesyoucanapplytoString,Stringlist,or Stringtablevariables.Eachofthesecontenttypescorrespondstoabuiltinsimpletype definedinthespecificationXMLSchemaPart2:Datatypes. Note: FordetailsaboutconstraintsforObjectsandObjectlists,seeAppendix C, SupportedDataTypes.

438

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Content Types anyURI

Description AUniformResourceIdentifierReference.ThevalueofanyURI maybeabsoluteorrelative. Constraining Facets enumeration,length,maxLength,minLength,pattern Note: TheanyURItypeindicatesthatthevariablevalueplaysthe roleofaURIandisdefinedlikeaURI.webMethodsIntegration ServerdoesnotvalidateURIreferencesbecauseitisimpractical forapplicationstocheckthevalidityofaURIreference.

base64Binary

Base64encodedbinarydata. Constraining Facets enumeration,length,maxLength,minLength,pattern

boolean

Trueorfalse. Constraining Facets pattern Example

true, 1, false, 0

byte

Awholenumberwhosevalueisgreaterthanorequalto128but lessthanorequalto127. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

-128, -26, 0, 15, 125

date

AcalendardatefromtheGregoriancalendar.Valuesneedto matchthefollowingpattern: CCYYMMDD WhereCCrepresentsthecentury,YYtheyear,MMthemonth,DD theday.ThepatterncanincludeaZattheendtoindicate CoordinatedUniversalTimeortoindicatethedifferencebetween thetimezoneandcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
1997-08-09

(August9,1997)

webMethods Developer Users Guide Version 7.1.1

439

F Validation Content Constraints

Content Types dateTime

Description Aspecificinstantoftime(adateandtimeofday).Valuesneedto matchthefollowingpattern: CCYYMMDDThh:mm:ss.sss WhereCCrepresentsthecentury,YYtheyear,MMthemonth,DD theday,Tthedate/timeseparator,hhthehour,mmtheminutes, andsstheseconds.ThepatterncanincludeaZattheendto indicateCoordinatedUniversalTimeortoindicatethedifference betweenthetimezoneandcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
2000-06-29T17:30:00-05:00represents5:30pmEasternStandard

timeonJune29,2000.(EasternStandardTimeis5hoursbehind CoordinatedUniversalTime.) decimal Anumberwithanoptionaldecimalpoint. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

8.01, 290, -47.24

double

Doubleprecision64bitfloatingpointtype. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example

6.02E23, 3.14, -26, 1.25e-2

440

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Content Types duration

Description Alengthoftime.Valuesneedtomatchthefollowingpattern: PnYnMnDTnHnMnS WherenYrepresentsthenumberofyears,nMthenumberof months,nDthenumberofdays,Tseparatesthedateandtime,nH thenumberofhours,nMthenumberofminutesandnSthe numberofseconds.Precedethedurationwithaminus()signto indicateanegativeduration. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
P2Y10M20DT5H50Mrepresentsadurationof2years,10months,20

days,5hours,and50minutes ENTITIES SequenceofwhitespaceseparatedENTITYvaluesdeclaredinthe DTD.RepresentstheENTITIESattributetypefromtheXML1.0 Recommendation. Constraining Facets enumeration,length,maxLength,minLength ENTITY NameassociatedwithanunparsedentityoftheDTD.Represents theENTITYattributetypefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace float Anumberwithafractionalpart. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
8.01, 25, 6.02E23, -5.5

webMethods Developer Users Guide Version 7.1.1

441

F Validation Content Constraints

Content Types gDay

Description Aspecificdaythatrecurseverymonth.Valuesmustmatchthe followingpattern: DD WhereDDrepresentstheday.ThepatterncanincludeaZatthe endtoindicateCoordinatedUniversalTimeortoindicatethe differencebetweenthetimezoneandcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example ---24indicatesthe24thofeachmonth

gMonth

AGregorianmonththatoccurseveryyear.Valuesmustmatchthe followingpattern: MM WhereMMrepresentsthemonth.ThepatterncanincludeaZat theendtoindicateCoordinatedUniversalTimeortoindicatethe differencebetweenthetimezoneandcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example --11representsNovember

gMonthDay

AspecificdayandmonththatrecurseveryyearintheGregorian calendar.Valuesmustmatchthefollowingpattern: MMDD WhereMMrepresentsthemonthandDDrepresentstheday.The patterncanincludeaZattheendtoindicateCoordinated UniversalTimeortoindicatethedifferencebetweenthetimezone andcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
--09-24representsSeptember24th

442

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Content Types gYear

Description AspecificyearintheGregoriancalendar.Valuesmustmatchthe followingpattern: CCYY WhereCCrepresentsthecentury,andYYtheyear.Thepattern canincludeaZattheendtoindicateCoordinatedUniversalTime ortoindicatethedifferencebetweenthetimezoneand coordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
2001indicates2001

gYearMonth

AspecificmonthandyearintheGregoriancalendar.Valuesmust matchthefollowingpattern: CCYYMM WhereCCrepresentsthecentury,YYtheyear,andMMthe month.ThepatterncanincludeaZattheendtoindicate CoordinatedUniversalTimeortoindicatethedifferencebetween thetimezoneandcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
2001-04indicatesApril2001

hexBinary

Hexencodedbinarydata. Constraining Facets enumeration,length,maxLength,minLength,pattern

ID

Anamethatuniquelyidentifiesanindividualelementinan instancedocument.ThevalueforIDneedstobeavalidXML name.TheIDdatatyperepresentstheIDattributetypefromthe XML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

IDREF

AreferencetoanelementwithauniqueID.ThevalueofIDREFis thesameastheIDvalue.TheIDREFdatatyperepresentsthe IDREFattributetypefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

webMethods Developer Users Guide Version 7.1.1

443

F Validation Content Constraints

Content Types IDREFS

Description SequenceofwhitespaceseparatedIDREFsusedinanXML document.TheIDREFSdatatyperepresentstheIDREFSattribute typefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength

int

Awholenumberwithavaluegreaterthanorequalto 2147483647butlessthanorequalto2147483647. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

-21474836, -55500, 0, 33123, 4271974

integer

Apositiveornegativewholenumber. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

-2500, -5, 0, 15, 365

language

Languageidentifiersusedtoindicatethelanguageinwhichthe contentiswritten.Naturallanguageidentifiersaredefinedin IETFRFC1766. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

long

Awholenumberwithavaluegreaterthanorequalto 9223372036854775808butlessthanorequalto 9223372036854775807. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example -55600, -23, 0, 256, 3211569432

Name

XMLnamesthatmatchtheNameproductionofXML1.0(Second Edition). Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

NCName

NoncolonizedXMLnames.Setofallstringsthatmatchthe NCNameproductionofNamespacesinXML. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

444

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Content Types negativeInteger

Description Anintegerwithavaluelessthanorequalto1. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

-255556, -354, -3, -1

NMTOKEN

Anymixtureofnamecharacters.RepresentstheNMTOKEN attributetypefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

NMTOKENS

SequencesofNMTOKENS.RepresentstheNMTOKENSattribute typefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength

nonNegativeInteger

Anintegerwithavaluegreaterthanorequalto0. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

0, 15, 32123

nonPositiveInteger

Anintegerwithavaluelessthanorequalto0. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits,whiteSpace Example

-256453, -357, -1, 0

normalizedString

Representswhitespacenormalizedstrings.Setofstrings (sequenceofUCScharacters)thatdonotcontainthecarriage return(#xD),linefeed(#xA),ortab(#x9)characters. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace Example

MAB-0907

webMethods Developer Users Guide Version 7.1.1

445

F Validation Content Constraints

Content Types positiveInteger

Description Anintegerwithavaluegreaterthanorequalto1. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

1, 1500, 23000

short

Awholenumberwithavaluegreaterthanorequalto32768but lessthanorequalto32767. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

-32000, -543, 0, 456, 3265

string

CharacterstringsinXML.AsequenceofUCScharacters(ISO 10646andUnicode).Bydefault,allwhitespaceispreservedfor variableswithastringcontentconstraint. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace Example

MAB-0907

time

Aninstantoftimethatoccurseveryday.Valuesmustmatchthe followingpattern: hh:mm:ss.sss Wherehhindicatesthehour,mmtheminutes,andsstheseconds. ThepatterncanincludeaZattheendtoindicateCoordinated UniversalTimeortoindicatethedifferencebetweenthetimezone andcoordinateduniversaltime. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example
18:10:00-05:00

(6:10pm,EasternStandardTime)Eastern StandardTimeis5hoursbehindCoordinatedUniversalTime. Representstokenizedstrings.Setofstringsthatdonotcontainthe carriagereturn(#xD),linefeed(#xA),ortab(#x9)characters, leadingortrailingspaces(#x20),orsequencesoftwoormore spaces. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

token

446

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Content Types unsignedByte

Description Awholenumbergreaterthanorequalto0,butlessthanorequal to255. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

0, 112, 200

unsignedInt

Awholenumbergreaterthanorequalto0,butlessthanorequal to4294967295. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

0, 22335, 123223333

unsignedLong

Awholenumbergreaterthanorequalto0,butlessthanorequal to18446744073709551615. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

0, 2001, 3363124

unsignedShort

Awholenumbergreaterthenorequalto0,butlessthanorequal to65535. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example

0, 1000, 65000

webMethods Developer Users Guide Version 7.1.1

447

F Validation Content Constraints

Constraining Facets
Whenyouapplyacontenttypetoavariable,youcanalsosetconstrainingfacetsforthe contenttype.Constrainingfacetsarepropertiesthatfurtherdefinethecontenttype.For example,youcansetaminimumvalueorprecisionvalueforadecimalcontenttype. Eachcontenttypehasasetofconstrainingfacets.Theconstrainingfacetsdescribedinthe followingtablecorrespondtoconstrainingfacetsdefinedinthespecificationXMLSchema Part2:Datatypes. Constraining Facet enumeration Description Thepossiblevaluesforthe variableatruntime. Usage Notes Ifyoualsoenteredpossible valuesusingthePick list choicespropertyinthe Generalcategoryofthe Propertiespanel,thosevalues willbedisplayedatruntime. However,theenumeration valueswillbeusedfor validation. fractionDigitsmustbelessthan orequaltototalDigits.

fractionDigits

Themaximumnumberofdigitsto therightofthedecimalpoint.For example,thefractionDigitsofthe value999.99is2. Thepreciseunitsoflength requiredforthevariablevalue. Theupperboundofarangeof possiblevalues.Therange excludesthevalueyouspecify.The variablecanhaveavaluelessthan butnotequaltomaxExclusive. Theupperboundofarangeof possiblevalues.Therange includesthevalueyouspecify.The variablecanhaveavaluelessthan orequaltomaxInclusive. Themaximumunitsoflength permittedforthevariablevalue.

length

Ifyouspecifylength,you cannotspecifyeither minLengthormaxLength. maxExclusivemustbegreater thanorequaltominExclusive. Youcannotspecify maxInclusiveandmaxExclusive forthesamecontenttype. maxInclusivemustbegreater thanorequaltominInclusive. Youcannotspecify maxInclusiveandmaxExclusive forthesamecontenttype. maxLengthmustbegreater thanorequaltominLength.

maxExclusive

maxInclusive

maxLength

448

webMethods Developer Users Guide Version 7.1.1

F Validation Content Constraints

Constraining Facet minExclusive

Description Thelowerboundofarangeof possiblevalues.Therangedoes notincludethevalueyouspecify. Thevariablecanhaveavalue greaterthanbutnotequalto minExclusive. Thelowerboundofarangeof possiblevalues.Therange includesthevalueyouspecify.The variablecanhaveavaluegreater thanorequaltominInclusive. Theminimumunitsoflength permittedforthevariablevalue. Apattern(regularexpression)that thevalueofthevariablemust match.Forexample,youcanusea regularexpressiontospecifythata variablethatisastringcontent constraintmatchaSocialSecurity numberformat. Themaximumnumberofdecimal digitsallowedinavalue.For example,thetotalDigitsofthevalue 999.99is5. Thewhitespacenormalization performedonthevariablevalue. ThevalueofwhiteSpacecanbeone ofthefollowing:
preserve:

Usage Notes minExclusivemustbelessthan orequaltomaxExclusive. Youcannotspecify minInclusiveandminExclusive forthesamecontenttype. minInclusivemustbelessthan orequaltomaxInclusive. Youcannotspecify minInclusiveandminExclusive forthesamecontenttype. minLengthmustbelessthanor equaltomaxLength.

minInclusive

minLength pattern

totalDigits

totalDigitsmustbegreater thanorequaltofractionDigits.

whiteSpace

Nowhitespace normalizationisperformed. Carriagereturns(#xD), linefeeds(#xA),andtabs(#x9)are replacedwithasinglespace (#x20). Afterthewhitespace normalizationspecifiedbyreplace isperformed,sequencesofspaces (#x20)andleadingandtrailing spaces(#x20)areremoved.

replace:

collapse:

webMethods Developer Users Guide Version 7.1.1

449

F Validation Content Constraints

Note: PreviousversionsofXMLSchemacontainedtheconstrainingfacetsduration, encoding,period,precision,andscale.However,theseconstrainingfacetsarenot includedintherecommendationofXMLSchemaPart2:Datatypes.Theconstraining facetsduration,encoding,andperiodwereremoved.precisionwasrenamedtotalDigits. scalewasrenamedfractionDigits.IfyouviewacontenttypefromanISschemacreated fromanXMLSchemaDefinitionthatusedpreRecommendationversionofXML Schema(beforeMay2001)theContentTypedialogboxwilldisplaytheconstraining facetsthatwereavailableinthepreRecommendationversionofXMLSchema. Note: Thewordfixedappearsnexttothenameofaconstrainingfacetwhosevalue isfixedandcannotbechanged.Whenafacethasafixedvalue,thefacetiscalleda fixedfacet.

450

webMethods Developer Users Guide Version 7.1.1

Validation Errors and Exceptions

452 452 465 470

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Developer Users Guide Version 7.1.1

451

G Validation Errors and Exceptions

Overview
Thisappendixdescribeserrormessagesthatcanoccurduringdatavalidation,ISschema generation,orISdocumenttypegeneration. WhenthevalidationengineinthewebMethodsIntegrationServervalidatesanobject(an XMLnode,thepipeline,ordocuments)andtheobjectdoesnotconformtotheblueprint ormodel,theservergenerateserrorsand/orexceptions.Youmightalsoreceiveerrors andexceptionswhencreatinganISschema.Thefollowingsectionsdescribetheerrors andexceptionsyoucanreceivewhenperformingvalidationandwhencreatinganIS schema.

Validation Errors
Whenyouperformvalidationusingabuiltinservice,webMethodsIntegrationServer returnsvalidationerrorsintheerrorsoutputvariableiftheobjectisinvalid.Whenyou performinput/outputvalidation,webMethodsIntegrationServerthrowsanexceptionif theinputsoroutputsareinvalid.Errormessagesarecontainedintheexception. Eachvalidationerrorcontainsacodeandadefaultmessage.Errorcodeprefixesindicate thevalidationerrortype: DTindicatesadatatypevalidationerror.Datatypevalidationerrorspertaintothe contenttypeconstraintsappliedtothevariables. NVindicatesanodevalidationerror.Nodevalidationerrorspertaintothevalidation ofanXMLnode. VVindicatesadocumentvalidationerror.Documentvalidationerrorspertaintothe structureofthedatavalues(forexample,aninvaliddocumentstructure). Thefollowingtabledescribesthevalidationerrorsyoucanreceivewhenperforming XML,pipeline,ordocumentvalidation. Error Code DT001 Message and Description [ISC.0082.9447] Value does not conform to datatype. Cause: Thevaluedoesnotmatchthespecifiedcontent type. DT002 [ISC.0082.9460] No matching enumeration value. Cause: Thevalueisnotanitemlistedintheenumeration field. DT003 [ISC.0082.9463] Length of value is not equal to specified length. Cause: Thesizeofthevaluedoesnotequalthenumber specifiedinthelengthfield.

452

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code DT004

Message and Description [ISC.0082.9464] Value is shorter than minimum length. Cause: Thesizeofthevalueislessthanthenumber specifiedintheminLengthfield.

DT005

[ISC.0082.9465] Value is longer than maximum length. Cause: Thesizeofthevalueisgreaterthanthenumber specifiedinthemaxLengthfield.

DT006

[ISC.0082.9489] Number of digits is greater than totalDigits. Cause: Thenumberofdigitsinthevalueisgreaterthan thenumberspecifiedinthetotalDigitsfield.

DT007

[ISC.0082.9490] Number of fraction digits is greater than fractionDigits. Cause: Thenumberofdigitstotherightofthedecimal pointisgreaterthanthenumberspecifiedinthe fractionDigitsfield.

DT008

[ISC.0082.9491] Value is less than minInclusive. Cause: Thevalueislessthanthevaluespecifiedinthe minInclusivefield.

DT009

[ISC.0082.9492] Value is less than or equal to minExclusive. Cause: Thevalueislessthanorequaltothevalue specifiedintheminExclusivefield.

DT010

[ISC.0082.9493] Value is greater than maxInclusive. Cause: Thevalueisgreaterthanthevaluespecifiedinthe maxInclusivefield.

DT011

[ISC.0082.9494] Value is greater than or equal to maxExclusive. Cause: Thevalueisgreaterthanorequaltothevalue specifiedinthemaxExclusivefield.

DT012

[ISC.0082.9448] Value does not match pattern. Cause: Thevaluedoesnotmatchthepatternspecifiedin thepatternfield.

DT013

[ISC.0082.9474] The input has invalid characters. Cause: ThespecifiedwhiteSpacevalueisinvalid.The valueofthewhiteSpacefieldcanbepreserve,replace,or collapse.

webMethods Developer Users Guide Version 7.1.1

453

G Validation Errors and Exceptions

Error Code DTBinary001

Message and Description [ISC.0082.9293] No matching choice value Cause: Thebinaryvalueisnotanelementlistedinthe choicesfield.

DTBinary002

[ISC.0082.9297] Value is shorter than minimum length Cause: Sizeofthebinaryvalue,inoctets,islessthanthe valuespecifiedintheminimum lengthfield.

DTBinary003

[ISC.0082.9298] Value is longer than maximum length Cause: Sizeofthebinaryvalue,inoctets,isgreaterthan thevaluespecifiedinthemaximum lengthfield.

DTBinary004

[ISC.0082.9296] Length of value is not equal to specified length Cause: Sizeofthebinaryvalue,inoctets,isnotequalto thevaluespecifiedinthelengthfield.

DTBoolean001

[ISC.0082.9246] Value does not conform to datatype Cause: ThevalueisnotaBoolean. [ISC.0082.9293] No matching choice value Cause: Thedecimalvalueisnotanelementlistedinthe choicesfield.

DTDecimal001

DTDecimal002

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsabledecimal. [ISC.0082.9294] Value is less than minimum Cause: Thedecimalvalueislessthanthevaluespecified intheminimum exclusiveorminimum inclusivefield.

DTDecimal003

DTDecimal004

[ISC.0082.9295] Value is greater than maximum Cause: Thedecimalvalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

DTDecimal005

[ISC.0082.9300] Value exceeds precision Cause: Thetotalnumberofdigitsinthedecimalvalueis greaterthanthevaluespecifiedintheprecisionfield.

DTDecimal006

[ISC.0082.9301] Value exceeds scale Cause: Thetotalnumberofdigitstotherightofthe decimalpointisgreaterthanthevaluespecifiedinthe scalefield.

454

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code DTDouble001

Message and Description [ISC.0082.9293] No matching choice value Cause: Thedoublevalueisnotanelementlistedinthe choicesfield.

DTDouble002

[ISC.0082.9294] Value is less than minimum Cause: Thedoublevalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTDouble003

[ISC.0082.9295] Value is greater than maximum Cause: Thedoublevalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

DTDouble004

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsabledouble. [ISC.0082.9293] No matching choice value Cause: Thefloatvalueisnotanelementlistedinthe choicesfield.

DTFloat001

DTFloat002

[ISC.0082.9294] Value is less than minimum Cause: Thefloatvalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTFloat003

[ISC.0082.9295] Value is greater than maximum Cause: Thefloatvalueisgreaterthanthevaluespecified inthemaximum exclusiveormaximum inclusivefield.

DTFloat004

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsablefloat. [ISC.0082.9293] No matching choice value Cause: Theintegervalueisnotanelementlistedinthe choicesfield.

DTInt001

DTInt002

[ISC.0082.9294] Value is less than minimum Cause: Theintegervalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTInt003

[ISC.0082.9295] Value is greater than maximum Cause: Theintegervalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

webMethods Developer Users Guide Version 7.1.1

455

G Validation Errors and Exceptions

Error Code DTInt004

Message and Description [ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsableinteger. [ISC.0082.9293] No matching choice value Cause: Theintegervalueisnotanelementlistedinthe choicesfield.

DTINTEGER001

DTINTEGER002

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsableinteger. [ISC.0082.9294] Value is less than minimum Cause: Theintegervalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTINTEGER003

DTINTEGER004

[ISC.0082.9295] Value is greater than maximum Cause: Theintegervalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

DTLong001

[ISC.0082.9293] No matching choice value Cause: Thelongvalueisnotanelementlistedinthe choicesfield.

DTLong002

[ISC.0082.9294] Value is less than minimum Cause: Thelongvalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTLong003

[ISC.0082.9295] Value is greater than maximum Cause: Thelongvalueisgreaterthanthevaluespecified inthemaximum exclusiveormaximum inclusivefield.

DTLong004

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsablelong. [ISC.0082.9293] No matching choice value Cause: Thesequenceofvaluesinthelistisnotanelement inthechoicesfield.

DTList001

DTList002

[ISC.0082.9297] Value is shorter than minimum length Cause: Sizeofthelistislessthanthevaluespecifiedinthe minimum lengthfield.

DTList003

[ISC.0082.9298] Value is longer than maximum length Cause: Sizeofthelistisgreaterthanthevaluespecifiedin themaximum lengthfield.

456

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code DTList004

Message and Description [ISC.0082.9299] Datatype definition is missing Cause: Datatypeorsimpletypedefinitionisnotfound.It ispossiblethatadependentISschemathatcontainsthis datatypedefinitionwasremovedfromtheISNamespace.

DTRecurringDuration001

[ISC.0082.9293] No matching choice value Cause: Therecurringdurationvalueisnotanelement listedinthechoicesfield.

DTRecurringDuration002

[ISC.0082.9294] Value is less than minimum Cause: Therecurringdurationvalueislessthanthevalue specifiedintheminimum exclusiveorminimum inclusive field.

DTRecurringDuration003

[ISC.0082.9295] Value is greater than maximum Cause: Therecurringdurationvalueisgreaterthanthe valuespecifiedinthemaximum exclusiveormaximum inclusivefield.

DTRecurringDuration004

[ISC.0082.9246] Value does not conform to datatype Cause: Therecurringdurationvaluedoesnotmatchthe patternspecifiedinthepatternfield.

DTSTR001

[ISC.0082.9293] No matching choice value Cause: Thestringvalueisnotanelementlistedinthe choicesfield.

DTSTR002

[ISC.0082.9297] Value is shorter than minimum length Cause: Thesizeofthestring,incharacters,islessthanthe valuespecifiedintheminimum lengthfield.

DTSTR003

[ISC.0082.9298] Value is longer than maximum length Cause: Thesizeofthestring,incharacters,isgreaterthan thevaluespecifiedinthemaximum lengthfield.

DTSTR004

[ISC.0082.9307] Does not match pattern(s) Cause: Thestringvaluedoesnotmatchthepattern specifiedinthepatternfield.

DTTime001

[ISC.0082.9293] No matching choice value Cause: Thetimevalueisnotanelementlistedinthe choicesfield.

webMethods Developer Users Guide Version 7.1.1

457

G Validation Errors and Exceptions

Error Code DTTime002

Message and Description [ISC.0082.9294] Value is less than minimum Cause: Thetimevalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTTime003

[ISC.0082.9295] Value is greater than maximum Cause: Thetimevalueisgreaterthanthevaluespecified inthemaximum exclusiveormaximum inclusivefield.

DTTime004

[ISC.0082.9246] Value does not conform to datatype Cause: Thetimevaluedoesnotmatchthepattern specifiedinthepatternfield.

DTTimeDuration001

[ISC.0082.9293] No matching choice value Cause: Thetimedurationvalueisnotanelementlistedin thechoicesfield.

DTTimeDuration002

[ISC.0082.9294] Value is less than minimum Cause: Thetimedurationvalueislessthanthevalue specifiedintheminimum exclusiveorminimum inclusive field.

DTTimeDuration003

[ISC.0082.9295] Value is greater than maximum Cause: Thetimedurationvalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

DTTimeDuration004

[ISC.0082.9246] Value does not conform to datatype Cause: Thetimedurationvaluedoesnotmatchthe patternspecifiedinthepatternfield.

DTTimePeriod001

[ISC.0082.9246] Values does not conform to data type Cause: Thetimeperiodvaluedoesnotmatchdatatype specifiedintheISschema.

DTTimePeriod002

[ISC.0082.9293] No matching choice value Cause: Thetimeperiodvalueisnotanelementlistedin thechoicesfield.

DTTimePeriod003

[ISC.0082.9294] Value is less than minimum Cause: Thetimedurationvalueislessthanthevalue specifiedintheminimum exclusiveorminimum inclusive field.

458

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code DTTimePeriod004

Message and Description [ISC.0082.9295] Value is greater than maximum Cause: Thetimedurationvalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

NV001

[ISC.0082.9001] Error while parsing Cause: TheXMLdocumentcannotbeparsed.Itispossible thattheXMLdocumentbeingvalidatedisnotwell formed.

NV002

[ISC.0082.9002] Unable to retrieve root element Cause: XMLdocumentisempty. Response: Checkthatthedocumentisbeingsubmitted properly.

NV003

[ISC.0082.9003] Unable to locate a matching element declaration Cause: Anundeclaredelementnodeisfoundinthe instancedocument. Response: Checktomakesurethatthedocumentuses onlydeclaredelements.

NV004

[ISC.0082.9004] [attributes] property must be empty Cause: Thiselementcarriesattributesthatarenot expected. Response: Checktomakesurethatthedocumentonly useselementattributesthataredeclaredintheschema.

NV005

[ISC.0082.9005] Element information items are not allowed in [children] property Cause: Thiselementcontainschildelements;however,the elementdeclarationintheISschemaindicatesthatthe elementdoesnotcontainanychildelements. Response: Checktomakesurethatthedocumentproperly conformstotheschema.

NV006

[ISC.0082.9006] Unable to locate a matching attribute declaration Cause: Thiselementcarriesanattributethatisnot declaredintheelementdeclarationintheISschema. Response: Checktomakesurethatthedocumentonly useselementattributesthataredeclaredintheschema.

webMethods Developer Users Guide Version 7.1.1

459

G Validation Errors and Exceptions

Error Code NV007

Message and Description [ISC.0082.9007] Missing Attribute Information Item Cause: Arequiredattributeisnotfoundinthiselement node. Response: Checktomakesurethatthedocument conformstotheschema.

NV008

[ISC.0082.9008] Invalid value - does not match fixed value Cause: Theinstancedocumentcontainsaninvalid elementbodyorattributevalue.Specifically,theelement bodyorattributevaluedoesnotmatchafixedvalue foundinthedeclaration. Response: Checktomakesurethatthedocument conformstotheschema.

NV009

[ISC.0082.9009] Child element elementName at position location is unexpected. Cause: Theelementisnotavalidchildelementorthe sequenceofchildelementsdoesnotsatisfytheorder specifiedinthecorrespondingelementdeclarationor complextypedefinition. Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9010] Incomplete contentone or more child elements are expected. Cause: Theelementisnotavalidchildelementorthe sequenceofchildelementsdoesnotsatisfytheorder specifiedinthedefinition. Response: Checktomakesurethatthedocument conformstotheschema.

NV010

[ISC.0082.9011] Unable to locate attribute declaration Cause: Anattributedeclarationisnotfound.Itispossible thatadependentISschemathatcontainsthisattribute declarationwasremovedfromtheISNamespace.For example,ISschemapub.schema.w3c:datatypesreferencesan attributedeclaration(xml:lang)inpub.schema.w3c:xml.If youreceivethiserror,itispossiblethatpub.schema.w3c:xml wasremoved. Response: Checktomakesurethatalloftheattribute declarationsreferencedbytheschemaarepresent.

460

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code NV011

Message and Description [ISC.0082.9012] Unable to locate type definition Cause: Asimpleorcomplextypedefinitionisnotfound. ItispossiblethatadependentISschemathatcontains thistypedefinitionwasremovedfromtheISNamespace. Forexample,ISschemapub.schema.w3c:structuresreferences atypedefinitioninpub.schema.w3c:datatypes.Ifyoureceive thiserror,itispossiblethatpub.schema.w3c:datatypeswas removed. Response: Checktomakesurethatallofthetype definitionsreferencedbytheschemaarepresent.

NV012

[ISC.0082.9014] Unable to locate element declaration Cause: Anelementdeclarationisnotfound.Itispossible thatadependentISschemathatcontainstheelement declarationwasremovedfromtheISNamespace. Response: Checktomakesurethatalltheelement declarationsreferencedbytheschemaarepresent.

NV013

[ISC.0082.9016] Unable to resolve QName: localName:{uri} Cause: Theschemaprocessorusesthenamespaces declaredintheinstancedocumenttoresolveaQNameto:

{Namespace URI} Local Name

However,theschemaprocessorisunabletoresolvethe QNameusingthenamespacedeclarationsintheinstance document. Response: Checktomakesurethatthedocument conformstotheschema. NV014 [ISC.0082.9017] typeName is not validly derived from declaredTypeName Cause: Thiserroroccurswhenthefirsttypeisusedina contextwherethesecondtypeisexpected,andeitherthe firsttypeisnotthesameasthesecondtypeorthefirst typeisnotvalidlyderivedfromthesecondtype. Response: Checktomakesurethatthecorrecttypesare specifiedintheschemaandthatthecorrect correspondingtypesareusedinthedocument.

webMethods Developer Users Guide Version 7.1.1

461

G Validation Errors and Exceptions

Error Code NV015

Message and Description [ISC.0082.9018] typeName is an abstract type and cannot be used directly to validate content Cause: Thespecifiedtypeisanabstracttypethathasbeen eitherdeclaredornominated.Abstracttypescannotbe usedtovalidateelementcontent. Response: Makesuretouseonlyconcretetypeswhen validatingelementcontent.

NV016

[ISC.0082.9019] elementName is an abstract element and cannot appear in an instance Cause: Theelementdeclarationidentifiestheelementas anabstractelement.Abstractelementscannotappearin instancedocuments. Response: Makesuretoonlyuseconcreteelementsin instancedocuments.

NV017

[ISC.0082.9020] QName - xsi:type is used incorrectly (declared type is anonymous) Cause: Atypeisnominatedusingxsi:typeforanelement whosedeclarationcontainsananonymoustype.Anew typecannotbederivedfromananonymoustypebecause newtypescanbederivedonlyfromnamedtypes. Response: Besuretouseonlynamedtypeswhen declaringnewtypes.

NV018

[ISC.0082.9021] Contains invalid text Cause: Theschemaprocessorencounteredaninvalid pieceoftext.Itispossiblethattheinstancedocument containsasimpletypewhereelementdeclarationsare interspersedwithtext.Simpletypescannotcontain elementdeclarations. Response: Checktomakesurethatthedocument conformstotheschema.

VV001

[ISC.0082.9025] Missing Object Cause: Arequireddocument(IDataobject)orvariableis missingfromtheinput. Response: Besurethattheargumentsarebeingpassed properlytothevalidator.

462

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Error Code VV002

Message and Description [ISC.0082.9026]UndefinedObjectfound Cause: Adocument(IDataobject)containsanorphan variable.(ThismessageonlyappearsiftheAllow unspecified fieldspropertyintheConstraintscategoryofthe PropertiespanelisFalse.) Response: Makesurethatallvariablesaredefined,or checktheboxtoallowunspecifiedfieldsonthe constraintstaboftheVariablePropertiesdialogbox.

VV003

[ISC.0082.9027] Dimension mismatch, List expected Cause: Thevaluebeingvalidatedisascalarvalueora multidimensionalarray(Stringtable),howeverthe variableitisbeingvalidatedagainstisalist(one dimensionalarray). Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9028] Dimension mismatch, Single item expected Cause: Thevaluebeingvalidatedisanarrayvalue(alist oratable).Thevariableitisbeingvalidatedagainstis scalar. Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9029] Dimension mismatch, Table expected Cause: Thevaluebeingvalidatedisascalarvalueoraone dimensionalarray(list).Thevariableitisbeingvalidated againstisatwodimensionalarray(table). Response: Checktomakesurethatthedocument conformstotheschema.

VV004

[ISC.0082.9030] Type mismatch, String expected Cause: ThevalueisbeingvalidatedagainstaString variable,buttheISdatatypeofthevalueisnotaString. Response: Checktomakesurethatthedocument conformstotheschema.

webMethods Developer Users Guide Version 7.1.1

463

G Validation Errors and Exceptions

Error Code

Message and Description [ISC.0082.9031] Type mismatch, Document expected Cause: ThevalueisbeingvalidatedagainstanIS documenttypevariable,buttheISdatatypeofthevalue isnotanISdocumenttype. Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9032] Type mismatch, Object expected Cause: ThevalueisbeingvalidatedagainstanObject variable,buttheISdatatypeofthevalueisnotanObject. Response: Checktomakesurethatthedocument conformstotheschema.

464

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Validation Exceptions
Atruntime,theserviceperformingvalidationeithersucceedsorfails.Iftheservicefails, webMethodsIntegrationServerthrowsavalidationexception.Avalidationexceptionis generatedifoneofthefollowingistrue: Errorsaredetectedintheobject(XMLnode,pipeline,ordocument(IDataobject)) thatispassed(forexample,nullvalue). Thebasicvalidationcontractisviolated(forexample,abinarytreeispassedinstead ofadocument(IDataobject)asexpected). Youspecifythattheserviceshouldfailiftheobjecttobevalidated(XMLnode, pipeline,ordocument(IDataobject))didnotconformtotheISschemaorIS documenttype(forexample,failIfInvalid=true).Ifthisisthereasonfortheexception, webMethodsIntegrationServerinsertsthevalidationerrorsintotheexception message. Thefollowingtableidentifiesanddescribesthevalidationexceptionsthatcanbe generated. Default Exception Message [ISS.0062.9021] object is null When is it thrown? Realtimeand designtime Description Cause: Theobjecttobevalidateddoes notexistinthepipeline. Response: LinkanXMLnodeor documentvariabletotheobject variableinService In. [ISS.0062.9022] %NSName% object does not exists Realtimeand designtime Cause: TheISdocumenttypeorIS schemaspecifiedfortheconformsTo variabledoesnotexistintheIS Namespace. Response: Changethevalueof conformsTotobeanISdocumenttype orISschemathatexistsintheIS namespace. [ISS.0062.9024] webMethods Integration Server does not support this type of validation (may or may not support in the future) Realtimeand designtime Cause: Theobjecttobevalidatedis notoneofthetypessupportedby validation. Response: Currently,onlyXML, pipeline,anddocument(IDataobject) validationissupported.

webMethods Developer Users Guide Version 7.1.1

465

G Validation Errors and Exceptions

Default Exception Message [ISS.0062.9202] Invalid: minLength

When is it thrown? Designtime

Description Cause: Themin lengthiseithernota parsablenumberorconflictswithmax length. Response: Changethemin lengthvalue andmakesurethatitiswithinthe allowedrangeforthecontenttype.

[ISS.0062.9203] Invalid: maxLength

Designtime

Cause: Themax lengthiseithernota parsablenumberorconflictswith minimumlength. Response: Changethemax lengthvalue andmakesurethatitiswithinthe allowedrangeforthecontenttype.

[ISS.0062.9211] Invalid Regular Expression: Expression

Designtime

Cause: ThepatternisaninvalidPerl regularexpression. Response: Modifythepatternand makesurethatitisPerlregular expression.

[ISS.0062.9212] Invalid: minInclusive

Designtime

Cause: ThespecifiedminInclusivevalue isinvalid.Forexample,the minInclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesuretheminInclusive isavalidnumberforthespecified contenttype.

[ISS.0062.9213] Invalid: minExclusive

Designtime

Cause: ThespecifiedminExclusive valueisinvalid.Forexample,the minExclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesuretheminExclusive isavalidnumberforthespecified contenttype.

466

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Default Exception Message [ISS.0062.9214] Invalid: maxInclusive

When is it thrown? Designtime

Description Cause: ThespecifiedmaxInclusive valueisinvalid.Forexample,the maxInclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesurethemaxInclusive isavalidnumberforthespecified contenttype.

[ISS.0062.9215] Invalid: maxExclusive

Designtime

Cause: ThespecifiedmaxExclusive valueisinvalid.Forexample,the maxExclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesurethemaxExclusive isavalidnumberforthespecified contenttype.

[ISS.0062.9230] Invalid scale

Designtime

Cause: Thevalueofaconstraining facethasaninvalidscale. Response: Examinetheconstraining facetvaluestomakesurethevalues donotconflict.

[ISS.0062.9231] Exceeds precision: minInclusive

Designtime

Cause: ThevalueoftheminInclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof minInclusiveortotalDigitstomakesure thevaluesdonotconflict.

[ISS.0062.9232] Exceeds precision: minExclusive

Designtime

Cause: ThevalueoftheminExclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof minExclusiveortotalDigitstomakesure thevaluesdonotconflict.

[ISS.0062.9233] Exceeds precision: maxInclusive

Designtime

Cause: ThevalueofthemaxInclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof maxInclusiveortotalDigitstomakesure thevaluesdonotconflict.

webMethods Developer Users Guide Version 7.1.1

467

G Validation Errors and Exceptions

Default Exception Message [ISS.0062.9234] Exceeds precision: maxExclusive

When is it thrown? Designtime

Description Cause: ThevalueofthemaxExclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof maxExclusiveortotalDigitstomakesure thevaluesdonotconflict.

[ISS.0062.9235] Invalid enumerated item

Designtime

Cause: Acontenttypeconstraintis definedintermsofthecollectiveset ofconstrainingfacetvalues.Together, thesevaluesdeterminetheallowed valuesandpropertiesofthecontent type.Theconstrainingfacetvalueyou justspecifiedmayconflictwithother constrainingfacetvalues.For example,ifyouspecifylengthforthe stringcontenttype,youcannot specifymin lengthormax length. Response: Examinetheconstraining facetvaluestomakesurethevalues donotconflictwitheachother.

[ISS.0062.9302] Maximum is less than minimum

Designtime

Cause: Invalidcondition.The maximumvalueislessthanthe minimumvalue. (maximum<minimum) Response: Changethemaximumor minimumvaluetoeliminatethe conflict.

468

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Default Exception Message [ISS.0062.9303] Minimum is out of range (Valid range is from lowerBound to upperBound)

When is it thrown? Designtime

Description Cause: Theminimumvalueisoutof thevalidrangeforthecontenttype. Response: Changetheminimumvalue (min exclusive,min inclusive,ormin length)andmakesurethatitiswithin theallowedrangeforthecontent type.

[ISS.0062.9304] Maximum is out of range (Valid range is from lowerBound to upperBound)

Designtime

Cause: Thespecifiedmaximumvalue isoutofthevalidrangeforthe contenttype. Response: Changethemaximum value(max exclusive,max inclusiveor max length)andmakesurethatitis withintheallowedrangeforthe contenttype.

webMethods Developer Users Guide Version 7.1.1

469

G Validation Errors and Exceptions

IS Schema Generation Errors and Warnings

WhenyoucreateanISschemafromaDTDoranXMLSchemadefinition,youmay receiveerrorsorwarnings.Thefollowingtableidentifiesanddescribestheerrorsyou mightreceivewhencreatinganISschema.ErrororwarningcodesthatbeginwithDTDC areerrorsthatoccurwhenyougenerateanISschemafromaDTD(orfromanXML documentthatreferencesanexistingDTD).ErrororwarningcodesthatbeginwithXSDC areerrorsthatoccurwhenyougenerateanISschemafromanXMLSchemadefinition. Note: YoumightalsoreceivetheseerrorsandwarningswhenyougenerateanIS documenttypeorflowservicefromanXMLSchemadefinition,DTD,orXML documentthatreferencesaDTD.FormoreinformationaboutcreatinganIS documenttype,seeCreatinganISDocumentTypeonpage 233.Formore informationaboutcreatingaflowservice,seeCreatingaNewFlowServiceon page 120. Code CONV001 Message and Description [ISC.0082.9101] Document type generation error: errorNumber. Cause: TheschemaprocessorencounteredanerrorintheXMLSchema definitionusedtocreateanISdocumenttype. Response: ContactSoftware AGCustomerCare. DTDC001 [ISC.0082.9501] DTD is empty Cause: TheDTDdoesnotcontainanyinformation. Response: MakesurethattheDTDisvalid. DTDC002 [ISC.0082.9502] NS Declaration is missing for prefix 'prefixName' Cause: WarnsthatanXMLNamespaceprefixisusedwithoutdeclaring it. Response: DeclaretheXMLNamespaceprefixbeforeusingit. DTDC003 [ISC.0082.9503] Error while parsing' Cause: WarnsthataDTDcannotbeparsed.ItispossibletheDTDdoes notsatisfyXML1.0. DTDC005 [ISC.0082.9505] Name collision detailedWarningMessage Cause: Warnsthatanelementtypedeclarationisfoundinanother schemawiththesameXMLNamespace. Response: UseadifferentXMLNamespace.

470

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Code XSDC001

Message and Description [ISC.0082.9703] Duplicate declaration found in this schema definition Cause: AduplicateattributeorelementdeclarationisfoundintheXML Schemadefinition. Response: MakesuretheXMLSchemadefinitionisvalid. [ISC.0082.9704] Duplicate definition found in this schema definition Cause: Aduplicatesimpletypeorcomplextypedefinitionisfoundin theXMLSchemadefinition. Response: MakesuretheXMLSchemadefinitionisvalid. [ISC.0082.9705] Definition not found Cause: Asimpletypeorcomplextypedefinitionismissingfromthe XMLSchemadefinition. Response: MakesurethedatatypedefinitionispresentintheXML Schemadefinition.

XSDC002

XSDC003

XSDC004

[ISC.0082.9706] Declaration not found Cause: Anerror.Anelementdeclarationorattributedeclarationis missingfromtheXMLSchemadefinition.

XSDC005

[ISC.0082.9707] Base type definition not found Cause: Abasetypedefinitionthatisusedtoderiveeitherasimpletype orcomplextypeismissingfromtheXMLSchemadefinition. Response: MakesurethebasetypedefinitionispresentintheXML Schemadefinition.

XSDC006

[ISC.0082.9708] Type derivation not OK Cause: Anerror.Asperthespec(s)fromtheW3C,thetypederivation isnotOK. [ISC.0082.9709] Type derivation not OK: attribute declaration to be restricted is not found in the base type definition Cause: Inacomplextypederivation,anattributedeclarationrestrictsthe useofanattribute.However,thisattributedeclarationisnotfoundin thebasetypedefinition. Response: Makesurethattheattributedeclarationispresentinthebase typedefinition.

webMethods Developer Users Guide Version 7.1.1

471

G Validation Errors and Exceptions

Code

Message and Description [ISC.0082.9710] Type derivation not OK: attribute declaration to be prohibited is not found in the base type definition Cause: Inacomplextypederivation,anattributedeclarationprohibits theuseofanattribute.However,thisattributedeclarationisnotfound inthebasetypedefinition. Response: Makesurethattheattributedeclarationispresentinthebase typedefinition.

XSDC008

[ISC.0082.9712] Incorrect facet (s) specified: typeName throws errorMessage. Cause: Constrainingfacetsappliedtothedatatypeareincorrector cannotbeusedwiththedatatype. Response: Usetheerrormessagestodeterminewhichconstraining facetstoremovefromthetypedefinition.

XSDC009

[ISC.0082.9713] Unable to resolve QName Cause: IncorrectQName. Response: CheckthevalueoftheQName. [ISC.0082.9701] Duplicate declaration found in this schema folderName:schemaNamewith the same target namespace Cause: Warnsthatanidenticalattributedeclarationorelement declarationisfoundinthespecifiedschemawiththesametarget namespace.Theschemaprocessorcreatestheschemabutdoesnot includetheduplicatedeclaration.Instead,theschemacontainsa pointertothefirst(original)declaration. Response: Nonerequired. [ISC.0082.9702] Duplicate definition found in this schema folderName:schemaName with the same target namespace Cause: Warnsthatanidenticalsimpletypeorcomplextypedefinitionis foundinthespecifiedschemawiththesametargetnamespace.The schemaprocessorcreatestheschemabutdoesnotincludetheduplicate typedefinition.Instead,theschemacontainsapointertothefirst (original)typedefinition. Response: Nonerequired.

XSDC080

XSDC081

472

webMethods Developer Users Guide Version 7.1.1

G Validation Errors and Exceptions

Code

Message and Description [ISC.0082.9106] Complex type TypeName is recursive. webMethods Integration Server does not support creating a document type from an XSD with a recursive complex type. Cause: TheXMLSchemacontainsarecursivecomplextypedefinition. TheIntegrationServerdoesnotsupportgeneratingadocumenttype fromanISschemacontainingarecursivecomplextype.Thiserroronly occurswhenyougenerateanISdocumenttypefromanXMLSchema. Response: Iftheschemayouareusingtogenerateadocumenttype containsarecursivecomplextypedefinition,selecttheGenerate complex types as document typesoptionwhenyoucreateanewdocumenttype fromanXMLSchemainDeveloper.

webMethods Developer Users Guide Version 7.1.1

473

G Validation Errors and Exceptions

474

webMethods Developer Users Guide Version 7.1.1

Index
Symbols
! 423 != 420 " 427 % 427 & 424 && 424 ( 427 ) 427 / 427 < 420 <= 421 <> 420 = 419 == 419 > 420 >= 420 \ 427 _env field 243 | 423 || 423 259 adding folders 121 packages 72 transformers 214 variables to pipeline link 211 addressing variables in expressions and filters 425 variables with special characters 426 alarm events building handlers for 360 definition of 348, 359 reasons generated 359 uses of 359 all content model 227 Allow unspecified fields option 256 and operator 424 annotating source code for jcode 320 anonymous type definitions 227 any attribute declaration 226 any element declaration 226 anyURI content constraint 439 API for Java services 314 applying conditions to links 204 constraints to variables 255, 438 areas of Developer window behavior and operation 31 editor 27 focus 31 general layout 21 Navigation panel 22 Properties panel 29 Recent Elements tab 27 resizing 33 Results panel 31 switching perspectives 34 UDDI Registry tab 25 zooming 33 arithmetic services 214 array variables default behavior for linking 409 definition of 409

A
access control 104 ACLs assigning to elements 104, 107 assigning to packages and folders 106 checking for services 105 defined 104 element creation, view, and deletion implications 112 inheritance 109 locking implications 111 requirements for using Developer 18 testing and debugging implications 111 viewing on a server 109 actions, performing on IS elements 32 adapter notifications described 243 guidelines for moving and copying 49 adapter services, retry behavior 376

webMethods Developer Users Guide Version 7.1.1

475

Index

guidelines for linking 203 linking to or from array variables 201, 409 linking to or from scalar variables 201, 409 linking to transformers 217 using in filters 429 assigning default value to a variable 207 replication services 85 shutdown services 85 startup services 85 universal names to services 137 values to pipeline variables 206, 207 variable values to a variable 208 version numbers to packages 78 attribute declaration 226 reference 226 audit data, when generated 142 audit events building handlers for 361 definition of 348, 360 when generated 142 Audit level property 149 audit log configuring 140 described 141 auditing configuring 140 failed and successful services 142, 146 failed services 142 for errors 146 for recovery, described 147 for resubmission purposes 146 long-running services 147 service retry 136 services 140 use cases 146 auditing options overwritten by server property 148 setting for a service 148 auditLog server property 148

B
base64Binary content constraint 439 blank labels in BRANCH steps 164 blue links, in the Pipeline tab 202

booleans content constraint 439 in filters, Broker restrictions 429 BRANCH step branching on empty values 164 branching on expressions 163 branching on null values 164 branching on switch value 160 creating 168 creating a multi-step child for 166 definition of 118, 384 Evaluate labels property 163 specifying default step 165 specifying label value 161 specifying switch variable 161 switch value 160 using conditional expressions 163 using in a flow 160 using SEQUENCE as a target of 166 using with regular expressions 161 breakpoints and the Trace Into command 289 clearing from flow steps 289 clearing from transformers 290 listing all 291 locating in flow services 291 overview 288 point when processing halts 289, 290 removing 291 setting in flow services 289 setting on a flow step 289 setting on a transformer 290 Broker filter collation locale 421 filter rules 428 Broker document type, creating publishable document type from 240 Broker/local trigger definition of 23 Broker/local triggers creating filters for 414 browser clients creating 341 invoking services from 342, 343 testing from 279

476

webMethods Developer Users Guide Version 7.1.1

Index

building event handler sample 357 event handlers 357 flow services 116 built-in services for arithmetic operations 214 for date/time transformations 214 for document (IData object) validation 263 for pipeline validation 264 for remote services 158 for string manipulation 214 for XML validation 264 invoking 158 throwExceptionForRetry 137 byte content constraint 439

C
C/C++ clients creating 335, 336 creating a make file 336 C/C++ services compiling with a make file 323 creating 323, 324 caching definition of 131 elements to improve Developer performance 66 services not suited for 131 services suited for 131 setting 133 using prefetch 133 call stack 278 catch sequence, in service retry 377 changing level of a step 154 passwords 37 position of a step 154 child flows described 154 stepping in/out of child flows 287 tracing 285 choice content model 227 circular dependencies, between packages 83 class files location of 318 clearing breakpoints on flow steps 289 breakpoints on transformers 290

client applications creating browser-based 341 creating C/C++ 335 creating Excel 339 creating Java 332 creating Visual Basic 337 closed documents, described 256 closing a session on webMethods Integration Server 35 coded services, about 308 collapsing transformers 220 white space 449 COM objects invoking as services 328 using with webMethods components 327 COM services creating 327 com.wm.app.b2b.server.ISRuntimeException class 137 combining Trace and Step commands 283 commands Disable Step 291, 293 Enable Step 291, 293 Load Pipeline Locally 299 Reset 283 Restore Pipeline from Server 299 Restore Pipeline Locally 299 Save Pipeline from Server 299 Save Pipeline Locally 297 Save Pipeline to Server 297 Set Breakpoint 289 Step 282, 286, 287 Step Into 282, 286, 287 Step Out 286, 287 Trace 282, 284 Trace Into 282, 284, 285 Trace to Here 282, 284, 285 comments for jcode 320 Comments property, definition 156, 388 compiling C/C++ services 327 error in Java compiler location 315 Java services 315, 321 services with Developer 315 services with jcode 321, 322 specifying the Java compiler 315

webMethods Developer Users Guide Version 7.1.1

477

Index

complex type definition all content model 227 anonymous 227 choice content model 227 described 227 empty content 227 expanding as inline IS document type 237 generating as separate IS document types 237 mixed content 227 recursive structures 237 sequence content model 227 composite mode (jcode) 322 conditional expressions addressing variables 425 addressing variables with special characters 426 lexical operators 421 logical operators 423 operator precedence 424 standard relational operators 419 syntax 415 using with pipeline links 204 using with the BRANCH step 163 conditional links creating 206 described 204 disabling 294 conditions applying to links 204 disabling on links 294 connecting to webMethods Integration Server 19, 35 constraining facets applying 258 described 255, 448 for pipeline validation 438 constraints content 224, 438 definition of 255 for IS schemas 224 for XML validation 224 structural 224 viewing for variables 259 content constraints applying to variables 255 constraining facets 255, 448 editing for simple types 231 for String variables, definition of 438 for validation 438 for variables, definition of 255

for XML validation 224 in IS schemas 224 in IS schemas, definition of 224 content models all 227 choice 227 empty 227 mixed 227 sequence 227 content types applying to variables 256 constraint symbol 259 customizing 257 specifiying constraining facet values 258 context-sensitive menus 32 Control steps BRANCH 118, 160 EXIT 118, 181 LOOP 118, 178 REPEAT 118, 170 SEQUENCE 118, 176 converting string lists to document (IData object) lists 200 copying by reference, definition of 196 by value, definition of 196 elements from the Results panel 277 IS elements 47 pipeline values 209 set values 209 transformers 219 creating code for Java services 315 event filters 352 event filters for services 355 event handler sample 357 event handlers 357 flow services 120 folders 121, 323 IS elements 41 IS schemas 229 Java services with an IDE 319 Java services with C/C++ 323 Java services with Developer 311, 314 Java services with Visual Basic 327 Java services with your own IDE 317 links to array variables 409 links to document (IData object) variables 198

478

webMethods Developer Users Guide Version 7.1.1

Index

packages 72 specifications for C/C++ services 323 version numbers for packages 78 cursors 309 customizing content types 257

D
dagger symbol, next to variable icon 259 data transformations, definition of 186 data types icons to represent 123 linking with Pipeline tab 199 supported by webMethods Integration Server 406 tables 409 data validation allowing undeclared variables 256 applying constraints 255 benefits of 254 blueprints for 254 closed variables 256 content constraints 255 definition of 254 document (IData object) validation 263 errors 452 exceptions 266, 465 input/output validation definition of 259 performing via Input/Output tab 261 performing via INVOKE step properties 262 open variables 256 pipeline validation 263 requiring variable existence 256 structural constraints 255 types of 254 XML validation 264 date content constraint 439 date conversion services 214 dateTime content constraint 440 DCOM objects invoking as services 328 using with webMethods Integration Server 327 debug level, setting on server 301 debugging flow services breakpoints 288 combining trace and step 283 disabling a single flow step 291 disabling a transformer 293 disabling conditions on links 294

dumping the pipeline to serveryyyymmdd.log 304 enabling a single flow step 291 enabling a transformer 293 modifying the pipeline 295 overview 270, 281 resetting debug mode 283 stepping into a child flow 287 stepping into a transformer 288 stepping through a flow 282, 286 tracing a flow 282, 284 tracing into a child flow 285 using server debug facility 300, 301 debugLog service 302 decimal content constraint 440 declaring input and output parameters 122 input for a service 123 output for a service 124 default value, assigning to a pipeline variable 207 defining packages 72 deleting breakpoints on transformers 290 event subscriptions 356 IS elements 53 links between variables 204 packages 77 dependencies, package identifying 81 removing 83 dependents checking when renaming IS elements 43 confirming before deleting elements 43 finding service and document (IData object) 60 safeguards for updating 44 details perspective 34 Developer window, toolbar 26 Developer. See webMethods Developer dimensionality, definition of 217 directories Java services 317 Disable Step command 291, 293 disabling a condition placed on a link 294 a flow step 291 a transformer 293 dispatch services for COM 328 for DCOM 328

webMethods Developer Users Guide Version 7.1.1

479

Index

document (IData object) validation definition of 263 errors 452 exceptions 465 performing 263 document data type 406 document list data type converting from String list 200 definition of 406 document reference data type creating 246 definition of 406 document reference list data type creating 246 definition of 406 Document Type Definitions. See DTDs document types. See IS document types documentation accessing for packages 76 additional 16 creating for packages 76 feedback 16 using effectively 15 documents (IData objects) applying content constraints 438 assigning to a document or document list 233, 246 assigning to a specification 233 benefits of 233 creating 233 errors when creating from DTD or XML Schema 470 finding dependents 43 linking 198 open and closed 256 pipeline validation 263 printing 245 using as service parameters 233, 245 viewing in browser 245 double content constraint 440 DROP modifier 190, 210 dropping values from the pipeline 210 DTDs creating documents (IData objects) from 233 creating IS document types from 235 creating IS schemas from 229 IS schema generation warnings 470 duration content constraint 441

E
edit perspective 34 editing elements. See editor event subscriptions 355 flow services 116 properties 30 Service property 157 simple types in IS schema 231 editor described 27 help about 38 hiding and showing 33 inserting flow steps into 153 resizing 33 supported data types 123 tabs 27 viewing and editing elements in 28 element declaration 226 element lock copying, moving, and deleting 94 removing. See unlocking elements system lock 88 user lock 88 element reference 226 elements (IS) See also editor 43 assigning ACLs 107 caching to improve Developer performance 66 copying 47 creating 41 cutting 47 definition of 40 deleting 53 displayed in editor 27 displayed in Navigation panel 22 displayed in Recent Elements tab 27 displayed in UDDI Registry tab 25 double-clicking to open 45 editing 43 exporting 78 finding dependents 43 finding in Navigation panel 55 finding unresolved references 62 fully-qualified names 41 guidelines copying 47 creating 41

480

webMethods Developer Users Guide Version 7.1.1

Index

deleting 53 general actions 44 moving 47 opening and closing 45 renaming 51 help for properties 38 locating in Navigation panel 29 locking 43 moving 47 naming guidelines 42 overwriting when creating publishable document types 241 pasting 47 performing actions 44 performing actions on 32 permissions 104 references 61 renaming 51 saving 53 single-clicking does not open 45 unlocking 43 viewing as HTML 43 empty content 227 strings in filters 421 values, branching on 164 Enable service audtiting options, described 141 Enable Step command 291, 293 enabling flow steps 291 service auditing 141 transformers 293 end-to-end linking 213 entering input for a service 272 ENTITIES content constraint 441 ENTITY content constraint 441 enumeration constraining facet 448 envelope field in publishable document types 243 usage restrictions 243 error auditing, described 146 error handling, in flow services 176 errors data validation 452 document (IData object) generation 470 flow service generation 470 IS schema generation 470 pipeline validation 452

Evaluate labels property 169 event filters creating 352 creating for services 355 event handlers creating 357 creating sample 357 definition of 350 for alarm events 360 for audit events 361 for exception events 363 for GD End events 366 for GD Start events 365 for port status events 367 for replication events 368 for session end events 369 for session expire events 370 for session start events 369 for stat events 370 for Tx End events 373 for Tx Start events 372 stages of creating 357 Event Manager alarm events building handlers 360 definition of 348, 359 uses 359 audit events building handlers 361 definition of 348, 360 definition of 348 event behavior 350 event handlers 350 Event Manager command 351 exception events 348, 362 building handlers 363 filters 352 GD End events 364 building handlers 366 uses 364 GD Start events 364 building handlers 365 uses 364 guaranteed delivery events 348 JMS retrieval failure events 348, 354 pattern strings 352

webMethods Developer Users Guide Version 7.1.1

481

Index

port status events 349, 366 building handlers 367 uses 366 replication events 349, 367 building handlers 368 uses 367 run-time behavior 350 security events 349 session end events 368 building handlers 369 session events 349, 368 uses 368 session expire events 368 building handlers 370 session start events 368 building handlers 369 stat events 349, 370 building handlers 370 uses 370 subscriptions creating 351 creating filters for 352 deleting 356 editing 355 managing 350 suspending 356 viewing 355 transaction events 349, 372 Tx End events 372 building handlers 373 uses 372 Tx Start events 372 building handlers 372 uses 372 viewing subscriptions 356 Event manager JMS delivery failure events 348, 354 events See also event handlers, Event Manager creating filters 352 creating filters for services 355 deleting subscriptions to 356 editing subscriptions to 355 guaranteed delivery 364 subscribing to 351 suspending subscriptions to 356 types of 348 viewing subscriptions to 355

Excel clients, creating 339 exception events building handlers for 363 definition of 348, 362 exceptions data validation 266, 465 during a test 277 executing services from Developer 271 execution locale 134 Exit on property 176 EXIT step creating 182 definition of 118, 386 using in a flow 181 expanding complex types inline 237 expanding transformers 220 explicit linking, definition of 192 explicit universal names 138 exporting elements and packages 78 expressions addressing variables 425 addressing variables with special characters 426 branching on 163 operator precedence 424 operators for 418 syntax for 415 using for pipeline linking 204 extending the Java class 313 extends (Java keyword) 313

F
facets, See constraining facets failIfInvalid property 465 failure of a flow step 176 of a REPEAT step 171 fields content type constraint symbol 259 dagger symbol 259 green squares 259 optional symbol 259 filter collation locale 421 filtering events 352 filters addressing variables 425 addressing variables with special characters 427 allowed quantifiers 429 arrays 429

482

webMethods Developer Users Guide Version 7.1.1

Index

back references 429 booleans in 429 braces {} in 429 checking for variable existence 429 collation locale, specifying 421 comparing strings and numeric values 429 comparison operators, missing 429 constrained Objects in 429 effect of locale 421 extended metacharacters 429 lexical relational operators 421 lists 429 logical operators 423 $null 429 operators for 418 server performance 419 standard relational operators 419 syntax 415 syntax restrictions 428 variables with special characters 426 finding elements in Navigation panel 55 invoked services 59 service and document (IData object) dependents 60 unresolved pipeline references 63 unresolved references 62 float content constraint 441 flow services See also services, debugging flow services breakpoints 288, 289 caching to improve Developer performance 66 creating 120 debugging 281 definition of 116 disabling a single step 291 disabling a transformer 293 disabling conditions placed links 294 editing 116 enabling a single step 291 enabling a transformer 293 errors creating from DTD or XML Schema 470 inserting steps in a service 153 maximum retry period 136 printing 149 response to failure 176 retrying 135, 136 stages of creating 120

stepping in/out of child flows 287 stepping in/out of transformers 288 stepping through 286 tracing 284 viewing in browser 149 flow steps BRANCH 118, 160 changing the level of 154 changing the position of 154 definition of 117 disabling 291 enabling 291 EXIT 118, 181 failure of 176 grouping 176 hierarchical order of 154 inserting into a flow service 152 INVOKE 117, 157 LOOP 118, 178 MAP 117, 183 moving in a flow service 154 parent/child relationships 154 properties 156 re-enabling 291 REPEAT 118, 170 SEQUENCE 118, 176 setting breakpoints on 289 folders, creating 121 frag mode (jcode) 321

G
GD End events building handlers for 366 definition of 364 pub.remote.gd:end 364 uses of 364 when generated 364 GD Start events building handlers for 365 definition of 364 pub.remote.gd:start 364 uses of 364 when generated 364 gDay content constraint 442 Generate Code command 334, 336, 337 generating complex types as document types 237 global declarations, in XML Schemas and DTDS 226

webMethods Developer Users Guide Version 7.1.1

483

Index

gMonth content constraint 442 gMonthDay content constraint 442 Go To Breakpoint command 291 Go To command (for services) 59 gray links, in the Pipeline tab 192 green square, next to variable icon 259 grouping flow steps 176 guaranteed delivery events See also GD End events, GD Start events compared to transaction events 364 definition of 348, 364 generating guaranteed delivery (GD) events 364 generating transaction (Tx) events 364 overview 364 when generated 364 guidelines for assigning startup, shutdown, and replication services 85 for creating IS document types 235 for elements creating 41 deleting 53 moving and copying 47 opening and closing 45 renaming 51 working with 44 for linking array variables 203 for linking document (IData object) variables 198 for linking variables 194 for linking variables of different data types 199 for naming packages 72 gYear content constraint 443 gYearMonth content constraint 443

H
hailmary mode (jcode) 322 hard-coding input variables 206 help, obtaining 38 hexBinary content constraint 443 hiding and showing panels 33 HTML, viewing elements in 43

I
ID content constraint 443 IData objects creating 309 definition of 308

getting data from 309 positioning cursors 309 putting data in 309 using in a Java service 319 IDE assigning a super class with 313 creating source code in 311 defining private methods with 313 implementing interfaces with 313 importing Java packages 313 in Developer 310, 311 using other IDEs 317 using the Java service editor 311 using the Shared tab 313 identifying package dependencies 81 replication services 85 shutdown services 85 startup services 85 IDREF content constraint 443 IDREFS content constraint 444 implementing interface in Java services 313 implements (Java keyword) 313 implicit linking described 192 for MAP steps 213 implicit universal names 138 import (Java keyword) 313, 319 import mechanism, in XML Schemas 230 importing Java packages 313, 319 include mechamism, in XML Schemas 230 index, array variables 202 Indexing tab. See linking array variables Input array property 179 input variables declaring for a service 122, 123 declaring in a document (IData object) 233 entering test values for 272 hard-coding 206 linking considerations 194 linking in the pipeline 192 loading values from a file 274 saving values to a file 274 input/output parameters declaring for a service 122 generating Java code from 315 Input/Output tab 125

484

webMethods Developer Users Guide Version 7.1.1

Index

input/output validation definition of 259 performing via Input/Output tab 261 performing via INVOKE step 262 inserting INVOKE step 158 steps into flow services 153 transformers 214 installing Java services 317 int content constraint 444 integer content constraint 444 Integrated Development Environment. See IDE Integration Server Administrator, unlocking elements 95 Integration Server. See webMethods Integration Server interfaces implementing in Java service 313 INVOKE step Comments property 388 creating 158 definition of 117, 388 finding 59 invoking built-in services 158 invoking services on another server 158 Label property 388 peforming validation via step properties 262 Pipeline tab 187 Scope property 388 Service property 157, 388 Timeout property 388 using in a flow 157 Validate input property 388 Validate output property 388 invoking built-in services 158 remote services 158 services 158 services from a browser 342, 343 services on another server 158 IS document types See also documents (IData objects) creating empty document types 234 creating from Broker document type 240 creating from DTD 235 creating from XML document 235 creating from XML Schema 235 described 233

editing 244 expanding complex types inline 237 generating complex types as document types 237 guidelines for creating 235 IS elements. See elements (IS) IS schemas appearance 224 constraints 224 content constraints 224 creating 229 definition of 224 editing simple types 231 errors from generating 470 generating multiple 230 import element 230 include element 230 structural constraints 224 using to validate an XML document 264 warnings from generating 470 ISRuntimeExceptions description of 135 throwing in services 376

J
Java classes for object and object list variables 407 Java clients, creating 332, 334 Java keywords extends 313 implements 313 import 313, 319 Java service editor 311 Java services adding private methods to 313 compiler location 315 compiling with Developer 315 compiling with jcode 321 creating 314, 315 creating with an IDE 317, 319 creating with Developer 311 extending the class of 313 implementing interface in 313 importing packages into 313, 319 installing manually 317 jcode requirements 320 location of class files 318 location of source files 318 publishing to the server 317 required code 319

webMethods Developer Users Guide Version 7.1.1

485

Index

setting run-time options 317 stages of development 311 structure of 310 using with webMethods components 310 validating from 265 jcode utility composite mode 322 frag mode 321 hailmary mode 322 make mode 321 purpose of 318 source code samples 432 source code tags 320 update mode 322 JMS delivery failure event 348, 354 JMS retrieval failure events 348, 354 JMS trigger definition of 23

K
keyboard shortcuts 32

L
L_EQUALS 422 L_GREATER_OR_EQUAL 422 L_GREATER_THAN 422 L_LESS_OR_EQUAL 422 L_LESS_THAN 422 L_NOT_EQUALS 422 Label property definition 388 for evaluating expressions 163 for general use 156 for specifying the default BRANCH step 165 for targeting BRANCH steps 161 language content constraint 444 length constraining facet 448 lexical relational operators conditional expressions 421 definition of 421 empty string 421 locale 421 non-string variables 421 libs directory 323, 327 link indices 202

linking array variables 201 default rules 409 guidelines for 203 to array variables 409 to scalar variables 409 to transformers 217 between document formats 213 conditional links 204 considerations 194 copying by reference 196 copying by value 196 default behavior for arrays 203 deleting links between variables 204 different data types 199 disabling conditions on links 294 document (IData object) variables 198 in a single view 213 input variables 192 output variables 193 pipeline variables to service variables 192 scalar variables to array variables 409 the pipeline 195 transformers 215 variables conditionally 204 variables explicitly 192 variables implicitly 192 links blue colored 202 deleting 204 disabling conditions 294 executing at run time 196 gray colored 192 in Pipeline tab 192 list variables in filters 429 Load Pipeline Locally command 299 loading input values from a file 274 pipeline values from a file into Results panel 299 overview 298 with restorePipelineFromFile service 299 locating a breakpoint 291 locking elements corresponding server files 98 description 88

486

webMethods Developer Users Guide Version 7.1.1

Index

Java and C/C++ 91 single element 91 system locking 92 template service 92 unlocking. See unlocking elements VCS check in/check out 88 viewing lock status 89, 93 log files, audit log 141 logging on to webMethods Integration Server 19, 35 logical operators, definition of 418 long content constraint 444 LOOP step creating 180 creating nested loops 178 definition of 118, 389 setting Input array 179 setting Output array 179 using in a flow 178

memory reducing usage 66 running out of during validation 267 menu bar, using to perform actions 32 metacharacters, in filters 429 methods, adding to a Java service 313 minExclusive constraining facet 449 minInclusive constraining facet 449 minLength constraining facet 449 mixed content 227 modifying the pipeline 190 moving IS elements 47 steps in a flow service 154 steps within a flow 154

N
Name content constraint 444 name transformations, definition of 186 namespace information (for services) creating source file from 322 location of 317 updating with jcode 321 namespaces usage in universal names 137 XML namespace property 247 naming services 41 Navigation panel described 22 help about 38 hiding and showing 33 icons 22, 88 refreshing contents of 25 resizing 33 toolbar 26 NCName content constraint 444 negativeInteger content constraint 445 NMTOKEN content constraint 445 NMTOKENS content constraint 445 nonNegativeInteger content constraint 445 nonPositiveInteger content constraint 445 not operator 423 notification, of server shutdown 36 ns directory 317 $null in filters 429 in labels for BRANCH steps 164 null, branching on 164

M
make file creating 323 using to compile C/C++ services 327 make mode (jcode) 321 MAP modifier definition of 190 executing at run time 196 linking different data types 199 linking from service output 193 linking to service input 192 MAP step debugging 288 definition of 117, 390 disabling transformers 293 enabling transformers 293 inserting transformers 214 Pipeline tab 189 transformers 213 using in a flow 183 using to initialize variables in a flow 184, 207 mapping. See linking Max attempts property 137 maxExclusive constraining facet 448 maximum retry period, definition of 136 maximum retry period, description of 136 maxInclusive constraining facet 448 maxLength constraining facet 448 maxOccurs threshold value, for validation 267

webMethods Developer Users Guide Version 7.1.1

487

Index

O
Object data type definition of 407 in filters 429 Object list data type, definition of 407 object list variables, Java classes 407 object variables, Java classes 407 online help, obtaining 38 open and closed documents 256 open documents, described 256 opening a session on webMethods Integration Server 35 operations, performing on IS elements 32 operators conditional expressions and filters 418 lexical relational operators 421 logical 423 precedence in expressions 424 relational 418 standard relational operators 419 optional variables for validation 256 or operator 423 out of sync publishable document types 244 Output array property 179 output templates assigning to a service 127 definition of 127 output variables declaring 124 declaring for a service 122 declaring in a document (IData object) 233 linking considerations 194 linking in the pipeline 193 Overwrite Pipeline Value option 207

P
packages adding 72 assigning version numbers 78 copying 74 creating 72 creating circular dependencies 83 cutting 74 definition of 70 deleting 77 dependencies, using with startup services 84 documenting 76 exporting 78

identifying dependencies 81 importing into Java services 313, 319 moving 74 naming guidelines 72 pasting 74 reloading 77 reloading vs refreshing 77 removing dependencies 83 required by Java services 319 viewing details 73 viewing patch history 79 panels editor 27 Navigation 22 Properties 29 Recent Elements 27 Results 31 switching perspectives 34 UDDI Registry 25 parameters applying constraints 255 benefits of declaring 122 declaring 122, 126 declaring for a service 123, 124 parent/child relationships in a flow 154 passwords changing 37 requirements 37 patch history removal by Integration Server 80 viewing for a package 79 pattern constraining facet 449 pattern matching, in event subscriptions 352 Perform Variable Substitution option 208 Performance 144 performance impact, service auditing 144 permission See also ACLs assigning to elements 104 Permissions property 107 perspectives of views 34 pipeline adding variables to 211 addressing variables 425 adjusting 190 assigning values to 206 changing values 295 checking for variables 418

488

webMethods Developer Users Guide Version 7.1.1

Index

conditional linking 204 copying values 209 definition of 118 DROP modifier 210 dropping values 295 dropping variables from 210 inspecting modifiers 63 linking 195 array variables 201 default rules 409 guidelines for 203 input variables 192 output variables 193 scalar variables, default rules 409 transformers 215 variables of different data types 199 MAP step 183 modifying 295 Overwrite Pipeline Value option 207 Perform Variable Substitution option 208 Pipeline In 187 Pipeline Out 188 restoring from a file 298 saving 296 saving from Results panel 297 saving with savePipelineToFile service 298 Service In 187 Service Out 188 SET VALUE modifier 206 stages of 187 validating 264 validating via built-in services 264 validating via Java service 265 viewing after run-time exception 279 viewing with Developer 275 Pipeline Editor. See Pipeline tab Pipeline In 187, 189 pipeline modifiers definition of 190 DROP 190 MAP 190 SET VALUE 190 Pipeline Out 188, 189 pipeline references definition of 63 finding 63

webMethods Developer Users Guide Version 7.1.1

489

Index

Pipeline tab 186 blue links (conditional link) 202 copying by reference 196 copying by value 196 default behavior for arrays 203 default linking rules 409 deleting links between variables 204 editing a MAP step 189 editing INVOKE step 187 gray links (implicit link) 192 inserting transformers 214 linking array variables 201 default rules 409 guidelines for 203 document (IData object) variables 198 scalar variables, default rules 409 transformers 215 variables 192 overview 186 printing 190 transformer movement 217 viewing in browser 190 pipeline validation definition of 263 errors 452 exceptions 465 performing via built-in services 264 performing via Java service 265 port status events building handlers for 367 definition of 349, 366 uses of 366 positiveInteger content constraint 446 precision constraining facet 449 prefetch 133 preserve white space 449 printing documents (IData objects) 245 flow services 149 Pipeline tab contents 190 private methods, defining in Java service 313 programming languages creating services with 308 supported 308 properties Audit level 149 auditLog server 148

Comments 156, 388 definition of 156 editing 30 Evaluate labels 169 Exit on 176 for transformers 215 Input array 179 Label 156, 388 Label (for BRANCH steps) 161, 165 Output array 179 Permissions 107 Repeat on 170, 171, 393 Scope 168, 388 Service 157, 159, 215, 388 setting for variables 247 Substitution groups 239 Switch 161, 168 Timeout 159, 168, 172, 180, 388 Validate input 159, 215, 388 Validate output 159, 215, 388 XML Namespace 247 Properties panel auditing a service 140 described 29 flow step properties 156 help about 38 hiding and showing 33 patch history for packages 80 resizing 33 run-time parameters 129 pub.flow:getRetryCount service 137 pub.flow:throwExceptionForRetry service 137 invoking 379 pub.publish:envelope document type 243 pub.remote.gd:end service 364 pub.remote.gd:start service 364 pub.remote:invoke service 158 pub.schema:validate service 263 pub.schema:validatePipeline service 264 publishable document types adapter notifications 243 creating from Broker document type 240 defined 240 editing 244 envelope field 243 overwriting elements 241 synchronizing 244 publishing services to the server 317

490

webMethods Developer Users Guide Version 7.1.1

Index

R
Recent Elements tab described 25, 27 help about 38 hiding and showing 33 resizing 33 Record data type. See document data type Record list data type. See document list data type Record Reference data type. See document reference data type Record Reference List data type. See document reference list data type records. See document (IData object), IS document types recursive complex types in XML Schemas 238 redefine mechanism, in XML Schemas 230 re-enabling flow steps 291 transformers 293 referenced elements, importing during synchronization 241 references finding 61 inspecting pipeline 63 refresh difference from restoring a session 36 Navigation panel contents 25 Recent Elements tab contents 27 regular expressions creating event filters with 355 definition of 398 operators 398 using as a BRANCH label 161 using in a mask 398 reinvoking services 146 relational operators definition of 418 lexical 421 standard 419 types of 418 reloading packages 77 remote servers, invoking services on 158 remote services, invoking 158 removing breakpoints 291 breakpoints from transformers 290 package dependencies 83 packages 77

replication services 86 shutdown services 86 startup services 86 variables from the pipeline 210 renaming IS elements 51 transformers 221 Repeat on property 170, 171, 393 REPEAT step creating (on failure) 172 creating (on success) 174 definition of 118, 391 failure 171 specifying the repeat condition 170, 171, 393 using in a flow 170 using to retry a failed step 171 using to retry a successful step 174 replace white space 449 replication events building handlers for 368 definition of 349, 367 uses of 367 replication services assigning 85 definition of 84 guidelines for assigning 85 removing 86 when to use 84 requirements for passwords 37 requiring variable existence for validation 256 Reset command 283 resizing panels 33 window areas 33 Restore Pipeline from Server command 299 Restore Pipeline Locally command 299 restorePipelineFromFile service 296, 298 restoring pipeline values from a file into Results panel 299 overview 298 with restorePipelineFromFile service 299 sessions 36 Results panel copying elements from 277 described 31 general information 276 help about 38

webMethods Developer Users Guide Version 7.1.1

491

Index

hiding and showing 33 resizing 33 saving results from 296 retried audit log status 136 Retry interval property 137 Retry on ISRuntimeException category 137 retry period, maximum 136 retry, for service 135 retrying a flow step 170 Run command 271 Run in Browser command 279 running out of memory, during validation 267 running services from Developer 271 run-time exceptions 277 run-time settings 317

S
Save Pipeline Locally command 297 Save Pipeline to Server command 297 savePipelineToFile service 298 saving changes to elements 53 elements (IS) 53 input values to a file 274 test results from Results panel 297 test results using savePipelineToFile service 298 test results, overview 296 scalar variables default behavior for linking 409 definition of 409 linking to or from array variables 409 scale constraining facet 448 schema browser, definition of 225 schema details area, definition of 228 schema editor 224 schema processor, definition of 229 schema services for document (IData object) validation 263 for pipeline validation 264 for XML validation 264 Scope property, definition 388 Send XML File command 280 sequence content model 227 SEQUENCE step as target for a BRANCH 166 definition of 118, 394 setting exit condition 176 using in a flow 176

server files, viewing for locked elements 98 server. See webMethods Integration Server serveryyyymmdd.log file 301 contents of 301 dumping pipeline to 304 overview 300 service auditing configuring 140 described 140 enabling 141 error auditing 146 failed and successful services 146 including pipeline 143 overwriting individual service settings 148 performance impact 142, 144 specifying which states to log 142 use cases 146 Service In 187 Service Out 188 Service property definition 388 definition of 157 editing 157 for transformers 215 renaming transformers with 221 service retry adapter services 376 audit log 136 basic componenents 377 configuring 135 example 380 overview 376 requirements 136, 376 restrictions 136 throwing exceptions for 376 services assigning universal names 137 audit data enabling 141 when generated 142 auditing configuring 140 enabling 141 for recovery 147 long-running services 147 options 148 caching to improve Developer performance 66 configuring retry 135

492

webMethods Developer Users Guide Version 7.1.1

Index

creating event filters for 355 creating flow 120 creating with Visual Basic 327 execution locale 134 finding dependents 43 finding invoked 59 input signature for trigger services 124 invoking built-in 158 invoking on another server 158 invoking on remote servers 158 locale policy 134 naming 41 provided by webMethods Integration Server 158 reinvoking 146 retry exceptions 376 retryiing 136 retrying adapter services 376 stages of creating 120 state information 130 testing and debugging 270 throwing retry exceptions 376 transformers 212 validating input/output via Input/Output tab 261 validating input/output via INVOKE step 262 session closing on webMethods Integration Server 35 opening on webMethods Integration Server 35 restoring 36 session end events building handlers for 369 definition of 368 session events See also session end events, session expire events, session start events definition of 349, 368 uses of 368 session expire events building handlers for 370 definition of 368 session start events building handlers for 369 definition of 368 Set Breakpoint command 289 SET VALUE modifier 190, 206 copying 209 using in MAP step 207

setting breakpoints on flow steps 289 breakpoints on transformers 290 variable values 206 Settings tab. See Properties panel Shared tab 313 short content constraint 446 shortcuts, for toolbars 26 showing and hiding panels 33 shutdown services assigning 85 definition of 84 guidelines for assigning 85 removing 86 when to use 84 signature for trigger services 124 of a service 308 simple types 227 editing in IS schema 231 single view linking 213 source code compiling with C/C++ make file 327 compiling with jcode 321, 322 creating automatically for a Java service 315 creating from namespace information 322 creating in your own Java IDE 319 creating Java 316 location of 318 tagging for jcode 320 writing in C/C++ 326 writing in Developer 311 source control system, integration with 88 Source field on Shared tab 313 Source tab. See Java service editor special characters in variable names 426 typing in expressions 427 specifications assigning to a service 251 benefits of 248 creating 248 definition of 248 finding dependents 43 squares, green 259 stack overflow, during validation 267

webMethods Developer Users Guide Version 7.1.1

493

Index

standard relational operators definition of 419 using in filters 419 using in triggers 419 starting Developer 19 startup services assigning 85 definition of 83 effect on package dependencies 84, 86 guidelines for assigning 85 removing 86 when to use 84 stat events building handlers for 370 definition of 349, 370 uses of 370 state information for a service 130 status events. See port status events Step command 282, 286, 287 Step Into command 282, 286, 287 Step Out command 286, 287 stepping through a flow 282, 286 string content constraint 446 String data type, definition of 406 String list data type converting to document list 200 definition of 406 String table data type 406 strings copying by reference 196 transformation services 214 structural constraints definition of 224, 255 for validation 255 for XML validation 224 IS schemas 224 structural transformations definition of 186 examples 200 linking to resolve 199 subordinate flow steps. See child flows subscribing to events, overview 351 Substitution group property 239 substitution groups 239 super class, defining in IDE 313 suspending event subscriptions 356 Switch property 161, 168 switch value, branching on 160

symbol for content type constraints 259 for optional variables 259 syntax for conditional expressions and filters 415 system locking defined 88 elements 92

T
tables, support of 409 tabs Input/Output tab 125 Pipeline tab 186 Schema tab. See schema editor 224 selecting 27 Settings tab for services. See also Properties panel 317 Shared tab 313 tagging source code for jcode 320 templates assigning to a service 127 definition of 127 test perspective 34 test results changing pipeline values 295 copying 277 loading 296 saving 296 viewing 275 testing services entering test input 272 from a browser 279 from Developer 271 inspecting the pipeline 275 loading input values from a file 274 loading the pipeline 296 overview 270 run-time exceptions 277 saving input to a file 274 saving the pipeline 296 setting breakpoints 288 testing in debug mode 281 viewing results 275 viewing the call stack 278 viewing the pipeline 279 XML document as input 280 threshold value, for maxOccurs 267 throw exception for retry 377

494

webMethods Developer Users Guide Version 7.1.1

Index

time content constraint 446 time conversion services 214 timeDuration content constraint 441 Timeout property 159 definition 388 for BRANCH step 168 for LOOPstep 180 for REPEAT step 172 token content constraint 446 toolbar, Developer window 26 toolbar, using to perform actions 32 totalDigits constraining facet 449 Trace command 282, 284 Trace Into command 282, 284, 285, 286 and breakpoints 289 effect on breakpoints 289 Trace to Here command 282, 284, 285 tracePipeline service 304 tracing a flow 282, 284 into a child flow 285 transaction events See also Tx End events, Tx Start events compared to guaranteed delivery events 364 definition of 349, 372 uses of 372 when generated 364 Transformer not found message 221 transformers adding 214 array variables 217 clearing breakpoints 290 collapsing 220 considerations 214 copying 219 debugging 288 definition of 212 dimensionality mismatch 217 disabling 293 enabling 293 expanding 220 inserting 214 linking 215 linking array variables 217 movement in Pipeline tab 217 output variables 216 properties 215 re-enabling 293

renaming 221 Service property 215 services provided by webMethods 214 setting breakpoints 290 stepping in/out of child flows 288 Validate input property 215 Validate output property 215 validating input and output 218 zooming in on 220 transient error, definition of 135, 376 trigger services, input signature requirements 124 triggers disabled when copied 48 filter syntax restrictions 428 filters and relational operators 421 lexical operators 418 testing 270 used with adapter notifications 243 using standard relational operators 419 troubleshooting information 16 try sequence, in service retry 377 Tx End events building handlers for 373 definition of 372 uses of 372 when generated 364 Tx Start events building handlers for 372 definition of 372 uses of 372 when generated 364 type definitions anonymous 227 complex types 227 simple types 227

U
Unicode, and Java source code 322 universal names assigning to services 137 implicit vs explicit 138 local portion of name 138 namespace portion of name 137 removing from a service 140 unlocking elements more than one 93 system locked 97

webMethods Developer Users Guide Version 7.1.1

495

Index

using Integration Server Administrator 95 using webMethods Developer 95 unresolved references, finding 62 unsignedByte content constraint 447 unsignedInt content constraint 447 unsignedLong content constraint 447 unSignedShort content constraint 447 update mode (jcode) 322 URL, invoking services from 342, 343 user account on webMethods Integration Server 18

V
Validate input property 159, 215 definition 388 Validate output property 159, 215 definition 388 validatePipeline service 264 validating See also validation documents (IData objects) 263 from Java services 265 input/output for transformers 218 input/output via Input/Output tab 261 input/output via INVOKE step 262 pipeline via built-in services 264 pipeline, overview 263 service input/output 259, 261, 262 XML documents 264 validation See also validating allowing undeclared variables 256 applying constraints 255 benefits of 254 blueprints for 254 constraining facets 448 constraints, definition of 255 content constraints 438 definition of 254 errors 266, 452 exceptions 266, 465 input/output 259 overview 254 requiring variable existence 256 running out of memory 267 service input and output 259 stack overflow 267 types of 254

XML validation 264 validation errors and error codes 452 validation services pub.schema:validate 263, 264 pub.schema:validatePipeline 264 value transformations, definition of 186 variables adding to the pipeline 211 addressing in the pipeline 425 applying constraints 255 applying content constraints 438 applying content types 256 checking for existence 418 content type constraint symbol 259 copying by reference 196 copying by value 196 copying values in pipeline 209 declaring for a service 122, 123, 124 declaring in a document (IData object) 233 deleting links 204 initializing values 207 linked by blue line 202 linking 192 linking conditionally 204 optional existence for validation 256 optional symbol 259 requiring existence for validation 256 setting properties 247 substitutions 208 using as Set Value 208 viewing applied constraints 259 XML Namespace property 247 VCS Integration feature, described 88 version control system (VCS), integration with 88 version numbers, assigning to packages 78 View as HTML command 149, 190, 245 view perspectives 34 viewing assigned value of a variable 207 breakpoints list 291 elements in HTML 43 status of a locked element 89, 93 test results 275 variable constraints 259 Visual Basic clients, creating 337 Visual Basic services creating 327

496

webMethods Developer Users Guide Version 7.1.1

Index

W
warnings document (IData object) generation 470 flow service generation 470 IS schema generation 470 watt.server.auditLog property, described 148 watt.server.invoke.maxRetryPeriod 136 watt.server.stats.pollTime property 366 webMethods Developer main window 21 online help 38 starting 19 toolbar 26 webMethods Integration Server access requirements for 18 closing a session 35 connecting to 19, 35 disconnecting from 35 logging on to 19 notification of shutdown 36 opening a session 35 performing ACL checking 105 supported data types 406 webMethods Monitor 140, 146 webMethods Type Library 333, 337, 339 When to include input pipeline options, described 143 When to log options, described 142 whiteSpace constraining facet 449 win32.COM.dispatch:createObject 328 windows layout 21 zooming 33 WmPublic package, definition of 158

X
XML documents creating documents (IData objects) from 233 creating IS document types from 235 creating IS schemas from 229 testing services with 280 XML Namespace property, described 247 XML Schema definitions creating documents (IData objects) from 233 creating IS document types from 235 creating IS schemas from 229 import mechanism 230 include mechanism 230 IS schema generation warnings 470 recursive complex types 238 redefine mechanism 230 referenced by other XML Schemas 230 XML validation content constraints 224 creating IS schemas 229 definition of 264 errors 452 exceptions 465 IS schemas, overview 224 performing 264 structural constraints 224

Z
zooming in a window 33 in on transformers 220

webMethods Developer Users Guide Version 7.1.1

497

Index

498

webMethods Developer Users Guide Version 7.1.1