Sie sind auf Seite 1von 522

TitlePage

Developing Integration Services


webMethods Developer Users Guide

Version 8.0

December 2009

Copyright & Docu mentID

ThisdocumentappliestowebMethodsDeveloperVersion 8.0andwebMethodsIntegrationServerVersion 8.0andtoallsubsequentreleases. Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions. Copyright19982009SoftwareAG,Darmstadt,Germanyand/orSoftwareAGUSA,Inc.,Reston,VA,UnitedStatesofAmerica,and/or theirlicensors. ThenameSoftwareAG,webMethods,andallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG and/orSoftwareAGUSA,Inc.and/ortheirlicensors.Othercompanyandproductnamesmentionedhereinmaybetrademarksoftheir respectiveowners. UseofthissoftwareissubjecttoadherencetoSoftwareAGslicensingconditionsandterms.Thesetermsarepartoftheproduct documentation,locatedathttp://documentation.softwareag.com/legal/and/orintherootinstallationdirectoryofthelicensedproduct(s). Thissoftwaremayincludeportionsofthirdpartyproducts.Forthirdpartycopyrightnoticesandlicenseterms,pleaserefertoLicense Texts,CopyrightNoticesandDisclaimersofThirdPartyProducts.Thisdocumentispartoftheproductdocumentation,locatedat http://documentation.softwareag.com/legal/and/orintherootinstallationdirectoryofthelicensedproduct(s).

Document ID: DEV-UG-80SP1-20091204

Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 17 17 18 18 21 22 22 23 25 26 26 29 29 30 31 31 33 35 35 35 36 37 37 37 38 39 40 40 41 41 42 43 44 45 45 46 46 47 47

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . .

48 49 51 51 51 52 53 55 57 58 60 60 62 63 64 64 65 67 70 70 73 74 74 76 76 77 77 79 80 81 82 82 83 84 86 87 88 88 89 89 89 90 91

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

Publishing and Retracting Information about Integration Server and Trading Networks Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing Metadata about Integration Server and Trading Networks Assets . . . . . . . Retracting Published Metadata about Integration Server and Trading Networks Assets Checking the Status of Publication and Retraction Requests . . . . . . . . . . . . . . . . . . . Status Information for Publication and Retraction Requests . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

91 92 93 94 94 97 98 98 99 99 99 100 100 101 102 102 103 104 104 104 106 107 108 108 109 109 110 110 111 111 113 114 114 114 116 116 117 118 119 120 120

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

How ACLs Affect Other Developer Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Testing/Debugging Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ACLs and Creating, Viewing, and Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up URL Aliases for Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Path Alias for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Pipeline Debug Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Pipeline Debug Property to Save the Service Pipeline . . . . . . . . . . . . . Using the Pipeline Debug Property to Restore the Service Pipeline . . . . . . . . . . . Configuring Service Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Maximum Retry Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Service Retry Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Universal Names to Services and Document Types . . . . . . . . . . . . . . . . . . . . . .

121 121 121 122 122 125 126 126 127 128 129 130 131 131 131 132 133 133 133 135 135 138 141 141 142 143 143 143 144 144 144 145 147 148 149 149 150 151 152 152 154

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Auditing for a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying When Audit Data Is Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including the Pipeline in the Service Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Is a Copy of the Input Pipeline Saved in the Service 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

157 158 158 160 160 162 162 163 163 164 164 165 166 167 168 169 170 171 172 173 173 174 174 174 176 176 177 177 179 180 181 182 184 186 186 187 187 188 190 192 192 194 195 196 196 198 200

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

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

201 202 202 203 205 206 206 207 207 211 213 214 215 215 216 218 219 219 220 221 222 222 223 223 224 225 226 227 227 229 229 231 232 232 233 233 233 234 234 235 236 237

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

9. Creating IS Schemas, IS Document Types, and Specifications . . . . . . . . . . . . . . . . . . 239 Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 What Does an IS Schema Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Schema Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Schema Details Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 About Schema Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Creating IS Schemas from XML Schemas that Reference Other Schemas . . . . . 247 Editing a Simple Type in an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Setting Constraining Facet Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Creating an Empty IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Creating an IS Document Type from an XML Document, DTD, or XML Schema . . . . 252 Points to Consider for All Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Points to Consider When Using a DTD As the Source . . . . . . . . . . . . . . . . . . . . . 252 Points to Consider When Using an XML Schema As the Source . . . . . . . . . . . . . 253 Expanding Complex Document Types Inline . . . . . . . . . . . . . . . . . . . . . . . . . 254 Generating Fields for Substitution Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Creating an IS Document Type from a Broker Document Type . . . . . . . . . . . . . . . . . . 259 The Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Adapter Notifications and Publishable Document Types . . . . . . . . . . . . . . . . . . . 262 Assigning Universal Names to an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . 262 Editing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Modifying Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Printing an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Using an IS Document Type to Specify Service Input or Output Parameters . . . . . . . 264 Using an IS Document Type to Build a Document Reference or Document Reference List Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Specifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 272 272 273 275 276 277 278 279 280 281 281 282 283 284 284 285

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 Through 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automatically Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . Manually Saving the Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restoring the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading a Saved Pipeline into the Results Panel . . . . . . . . . . . . . . . . . . . . . . . . . Automatically Loading a Saved Pipeline at Run Time . . . . . . . . . . . . . . . . . . . . . . Manually 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

287 288 288 289 290 292 292 293 295 295 296 297 298 299 299 300 301 301 302 303 304 305 306 307 307 308 309 310 310 311 312 313 315 315 316 316 317 317 318 319 319 320 320 321 321 322 322 323

10

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

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

325 326 326 326 327 327 328 328 329 329 329 331 332 333 335 335 335 336 336 337 337 337 338 338 339 339 340 341 342 342 343 345 345 345 346 347 349 350 350 350 351 352 352

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11

Table of Contents

Building a C/C++ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Visual Basic Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. Submitting and Receiving XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Receiving XML in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTPing a File from a webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Sending XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

353 353 353 354 354 355 355 355 355 356 356 356 357 357 357 358 358 358 358 359 360 360 360 361 361 362 362 364 365 366 366 366 367 367 368 369 369 370 371 372 372 373 374 374 374 375

12

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

15. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Event Handlers Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . Working with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Exception Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Guaranteed Delivery Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guaranteed Delivery Events and Transaction Events . . . . . . . . . . . . . . . . . . . . . . Working with JMS Delivery Failure Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with JMS Retrieval Failure Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Port Status Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Replication Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Security Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Stat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . .

377 378 380 380 381 381 383 385 386 386 387 387 388 390 391 391 392 392 392 393 394 394 395 395 395 396 397 397 399 400 400 401 401 402 404 407 408 408 408 409 410

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13

Table of Contents

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

410 411 411 412 412 412 413 413 414 414 415 415 415 416 417 417 418 418 419 421 422 422 422 429 430 431 433 433 437 438 439 441 442 442 442 443 445 447 448 449 450 451 452

14

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Table of Contents

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

455 456 456 456 461 462 463 473 477 478 478 492 497

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15

Table of Contents

16

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

About This Guide


ThisguidedescribeshowtocreateservicesusingwebMethodsDeveloper.Itcontains informationfordeveloperswhowanttobuildservicesusingthewebMethodsflow languageoraprogramminglanguagesuchasJava,C/C++,orVisualBasic. Tousethisguideeffectively,youshouldknowhowtoprograminJava,C/C++,and/or VisualBasicifyouwillbecreatingservicesinthoselanguages. Note: Thisguidedescribesfeaturesandfunctionalitythatmayormaynotbeavailable withyourlicensedversionofwebMethodsIntegrationServer.Forinformationabout thelicensedcomponentsforyourinstallation,seetheSettings > Licensepageinthe webMethodsIntegrationServerAdministrator.

Terminology
Thefollowingtermsareinterchangeable: ISdocumenttypeandESBdocumenttype ISserviceandESBservice

Document Conventions
Convention Bold Narrow font UPPERCASE Italic Description Identifieselementsonauserinterface. IdentifiesstoragelocationsforservicesonwebMethodsIntegration Server,usingtheconventionfolder.subfolder:service. Identifieskeyboardkeys.Keysyoumustpresssimultaneouslyare joinedwithaplussign(+). Identifiesvariablesforwhichyoumustsupplyvaluesspecifictoyour ownsituationorenvironment.Identifiesnewtermsthefirsttimethey occurinthetext. Identifiestextyoumusttypeormessagesdisplayedbythesystem. Indicatesasetofchoicesfromwhichyoumustchooseone.Typeonly theinformationinsidethecurlybraces.Donottypethe{}symbols. Separatestwomutuallyexclusivechoicesinasyntaxline.Typeoneof thesechoices.Donottypethe|symbol.

Monospace font

{} |

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

17

About This Guide

Convention [] ...

Description Indicatesoneormoreoptions.Typeonlytheinformationinsidethe squarebrackets.Donottypethe[]symbols. Indicatesthatyoucantypemultipleoptionsofthesametype.Type onlytheinformation.Donottypetheellipsis(...).

Documentation Installation
YoucandownloadtheproductdocumentationusingtheSoftware AGInstaller. DependingonthereleaseofthewebMethodsproductsuite,thelocationofthe downloadeddocumentationwillbeasshowninthetablebelow. For webMethods... 6.x 7.x 8.x The documentation is downloaded to... Theinstallationdirectoryofeachproduct. Acentraldirectorynamed_documentationinthemain installationdirectory(webMethodsbydefault). Acentraldirectorynamed_documentationinthemain installationdirectory(Software AGbydefault).

Online Information
YoucanfindadditionalinformationaboutSoftware AGproductsatthelocationslisted below. Note: TheEmpowerProductSupportWebsiteandtheSoftware AGDocumentation WebsitereplaceSoftware AGServLine24andwebMethodsAdvantage. If you want to... Accessthelatestversionofproduct documentation. Go to... Software AG Documentation Web site http://documentation.softwareag.com

18

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

About This Guide

If you want to... Findinformationaboutproductreleasesand toolsthatyoucanusetoresolveproblems. SeetheKnowledgeCenterto: Readtechnicalarticlesandpapers. Downloadfixesandservicepacks. Learnaboutcriticalalerts. SeetheProductsareato: Downloadproducts. Getinformationaboutproduct availability. Accessolderversionsofproduct documentation. Submitfeature/enhancementrequests. Accessadditionalarticles,demos,and tutorials. Obtaintechnicalinformation,useful resources,andonlinediscussionforums, moderatedbySoftware AGprofessionals, tohelpyoudomorewithSoftware AG technology. Usetheonlinediscussionforumsto exchangebestpracticesandchatwith otherexperts. Expandyourknowledgeaboutproduct documentation,codesamples,articles, onlineseminars,andtutorials. LinktoexternalWebsitesthatdiscuss openstandardsandmanyWeb technologytopics. Seehowothercustomersarestreamlining theiroperationswithtechnologyfrom Software AG.

Go to... Empower Product Support Web site https://empower.softwareag.com

Software AG Developer Community for webMethods http://communities.softwareag.com/ webmethods

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

19

About This Guide

20

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Getting Started with Developer


22 22 23 25 35 39 41 42

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

21

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,seeStoringServicesinaVersionControlSystemin theSoftware AG_directory\_documentationdirectory.

Before You Use Developer


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

22

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

23

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.

24

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 26. UDDI Registry tab.YouusetheUDDIRegistrytabtoconnecttoanddisconnectfroma UDDIRegistry,andtodisplay,filter,andpublishWebservices.Formoreinformation aboutthispanel,seeTheUDDIRegistryTabonpage 29. Recent Elements tab.YouusetheRecentElementstabtoquicklyaccesselementsyou haverecentlyviewed.Formoreinformationaboutthispanel,seeTheRecent ElementsTabonpage 31. Editor.Youusetheeditortoexamineandeditanelementyouopenedfromthe NavigationpanelorRecentElementstab.Formoreinformationabouttheeditor,see TheEditoronpage 31. Properties panel.YouusethePropertiespaneltoviewandeditthepropertiesforan item.Formoreinformationaboutthispanel,seeThePropertiesPanelonpage 33. Results panel.YouusetheResultspaneltoviewtheresultofaservicesexecution,to viewthevariablesthataserviceaddstothepipeline,andtoviewthecontentsof thosevariables.Formoreinformationaboutthispanel,seeTheResultsPanelon page 35. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

25

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,seeStoringServicesinaVersionControlSysteminthe Software AG_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.

26

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

27

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.

28

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

29

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.

30

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 youattempttoopenanelementthatwasdeletedafteryouclosedyourprevious Developersession,Developeralertsyouthattheelementcannotbefoundandthen removestheelementfromthelist. IfyouattempttoopenanelementlistedintheRecentElementstabthatanotheruser hasdeleted,moved,orrenamedduringyourDevelopersession,Developerdisplaysa messagealertingyouthattheelementcannotbefound. Ifyoumoveorrenameanelementduringyourcurrentsession,Developer automaticallyrefreshestheRecentElementstabtoreflectthechange.Ifyoudeletean element,DeveloperremovestheelementfromtheRecentElementslist. FormoreinformationaboutselectingelementsintheRecentElementstabtovieworedit intheeditor,seeOpeningandClosingElementsintheEditoronpage 49.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

31

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 26 andWhatIsaLock?onpage 98. Tip! YoucanpressCTRL+ALT+RIGHTARROWtotoggleforwardbetweenopen elementsintheeditorandCTRL+ALT+LEFTARROWtotogglebackward.

32

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

33

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.

34

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

35

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.

36

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

37

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.

38

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 23. ClickOK. Important! WhileyouhaveanopensessiononaserverthroughDeveloper,youare usingalicensedseatforthatserver.Attimeswhenyouarenotactivelyusing Developer,youmaywanttocloseyoursessiontofreeaseatontheserverforothers touse.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

39

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

Notification of Server Shutdown


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

40

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Ifyoudidnotsaveyourworkbeforeshutdownoccurred,youmightbeabletorestore yoursessionwhentheserverrestartsandthensaveyourwork.Formoreinformation aboutrestoringsessions,seeRestoringaSessiononaServeronpage 40.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

41

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.

42

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Managing Elements in the Navigation Panel


44 45 47 48 49 51 55 57 58 60 64 67 70

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

43

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 StoringServicesinaVersionControlSysteminthe directory: Software AG_directory\_documentation Chapter 3,WorkingwithPackages

44

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

2 Managing Elements in the Navigation Panel

Creating New Elements


Whencreatingelements,keepthefollowingpointsinmind: YoucannotcreateanewJavaorCserviceunlessallservicesofthosetypesare unlocked,orlockedbyyou,inthefolderinwhichyouwanttocreatethenewservice. Fordetails,seeLockingJavaandC/C++Servicesonpage 101. Thenamesofnonfolderelementsmustbeuniqueacrossallpackages.Ifyoutryto createanelementusinganamethatalreadyexistsatthatlevelinanypackage, DevelopercreatestheelementandnamesitUntitled. Developerplacessomerestrictionsonthecharactersyoucanuseinelementand packagenames.Formoreinformationabouttheserestrictions,seeGuidelinesfor NamingElementsonpage 46. 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,Developeroffersonlythe All Choicesoption,whichopenstheNewdialogboxdescribedintheprocedureabove.

About Element Names


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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

45

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.

46

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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,seeStoringServicesinaVersionControl SystemintheSoftware AG_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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

47

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

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

48

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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. IftheDevelopersVersionControlSystemIntegrationfeature(VCS)isenabled, Developermightexhibitslowdowns,errormessages(suchasServerversionhas changedandSessionalreadyinuse),andmaystoprespondingcompletelywhen youexpandalargeelement(suchasafolder)intheNavigationpanel.Thiscondition occurswhenDeveloperqueriestheIntegrationServertocheckthelockstateofeach elementwithinanelement.Toimproveperformanceduringlockchecking,see OptimizingLockCheckingonpage 77.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

49

2 Managing Elements in the Navigation Panel

To open elements in the editor 1 Selectoneormoreelementstoopen. Tip! PresstheSHIFTkeyasyouclicktoselectagroupofadjacentelements.Press theCTRLkeytoselectagroupofnonadjacentelements. 2 OntheFilemenu,clickOpen. IfyouareopeninganelementfromtheRecentElementstabandtheelementresides onaservertowhichyouarenolongerconnected,Developerpromptsyoutologon tothatserverbeforedisplayingtheelement. 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.

50

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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,Developerwillupdatethereferencetotheinvoked service.

Moving and Copying Services


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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

51

2 Managing Elements in the Navigation Panel

YoucannotmoveorcopyaJavaservicetoafolderthatcontainsotherJavaservices thataresystemlockedorlockedbyanotheruser.Ifyouattempttodoso,Developer cancelstheentiremove/copyaction. WhenyoumoveorcopyaJavaservice,Developerwillalsomoveorcopythe servicesSharedfieldstothedestinationfolder,unlessthedestinationfolderalready containsSharedfieldswithdifferentvalues.Inthiscase,youmustfirstmanually copytheSharedfieldsintothedestinationfolderandthenmoveorcopytheJava service.

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

52

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

2 Managing Elements in the Navigation Panel

Whenyoumoveorcopyapublishabledocumenttypetoadestinationonthesame server,themovedorcopieddocumenttyperemainspublishable.Whenyoucopya publishabledocumenttypetoadifferentserver,Developerconvertsthepublishable documenttypetoanISdocumenttypeonthedestinationserver.Formore informationaboutmakingISdocumenttypespublishableandsynchronizingthem withBrokerdocumenttypes,seethePublishSubscribeDevelopersGuide. Tip! ToretainthestatusofapublishabledocumenttypeanditslinktoaBroker documenttype,usethepackagereplicationfunctionalityintheIntegrationServer AdministratorinsteadofusingDevelopertomoveorcopythepackage containingthepublishabledocumenttype.Forinformationaboutpackage replication,seeAdministeringwebMethodsIntegrationServer.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

53

2 Managing Elements in the Navigation Panel

IfyoudonothaveReadaccesstotheelementsyouaremovingorcopying,orWrite accesstothelocationyouaremoving/copyingthemto,Developerdisplaysamessage thatidentifiestheelementsthatarepreventingtheactionfromcompleting successfully.ClickOKandtheneitherobtaintheproperaccessfromyoursystem administratororselectonlythoseelementstowhichyouhaveproperaccess. Selectthelocationwhereyouwanttomoveorcopytheelements. OntheEditmenu,clickPasteAfter. Ifthedestinationalreadycontainsanelementwiththesamenameasanelementyou aremovingorcopying,dooneofthefollowing:

5 6 7

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

Formoreinformationaboutrenamingelements,seeRenamingElementson page 55. 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.)

54

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

2 Managing Elements in the Navigation Panel

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

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

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 47. Tip! Youcanalsomoveelementsbyclickinganddraggingthemtotheirnewlocation.

Renaming Elements
Whenrenamingelements,keepthefollowingpointsinmind: YoucanrenameanyelementsforwhichyouhaveWriteaccesstotheelementandits parentfolder.Whenrenamingafolder,youmustalsohaveWriteaccesstoall elementswithinthefolder.FormoreinformationaboutWriteaccessandACLs assignedtoelements,seeChapter 5,AssigningandManagingPermissions. Whenyourenameafolder,Developerautomaticallyrenamesalloftheelementsin thatfolder(thatis,changestheirfullyqualifiednames). Ifthefolderyouwanttorenamecontainselementswithunsavedchanges,youmust savethechangesbeforeyoucanrenamethefolder.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

55

2 Managing Elements in the Navigation Panel

Elementnamesmustbeuniqueacrossallpackages.Ifyoutrytorenameanelement usinganamethatalreadyexistsatthatlevelinanypackage,Developerrevertsthe elementbacktoitsoriginalname. Whenyourenameanadapternotification,Developeralsorenamesitsassociated publishabledocumenttypeandpromptsyoutoindicatewhethertorenamethe associatedBrokerdocumenttype. Youcannotrenamealistenerorconnectionelement. 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 Click... Save and Proceed Proceed without Save Cancel

56

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

2 Managing Elements in the Navigation Panel

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

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 47.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

57

2 Managing Elements in the Navigation Panel

Deleting Elements
Whendeletingelements,keepthefollowingpointsinmind: YoucandeleteanyelementstowhichyouhaveWriteaccessfortheelementandits parentfolder.Whendeletingafolder,youmustalsohaveWriteaccesstoallelements withinthefolder.FormoreinformationaboutWriteaccessandACLsassignedto elements,seeChapter 5,AssigningandManagingPermissions. WhenyoudeleteafolderorthelastJavaserviceinafolder,Developeralsodeletes thesharedsourceforthatfolder.Ifyoucancelthedeleteaction,noelements (includingnonJavaserviceelements)aredeleted. Youcanonlydeleteanadapternotificationspublishabledocumenttypeifyoudelete itsassociatedadapternotification. Whenyoudeleteanadapternotification,Developeralsodeletesitsassociated publishabledocumenttypeandpromptsyoutoindicatewhethertodeletethe associatedBrokerdocumenttype. Youcannotdeletealistenerorconnectionelement. 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 Click... Save and Proceed Proceed without Save Cancel

Iftheelementsyouaredeletingarenotdependentsofotherelements,Developer promptsyoutoconfirmthedeleteaction.ClickOK.

58

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

2 Managing Elements in the Navigation Panel

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. 2 Continueorcancelthedeleteactionasfollows: To... DeletetheelementsfromtheNavigationpanel(and thereforebreakanylinkstodependentelements) Canceltheentiredeleteaction Click... Continue Cancel

Formoreinformationaboutdependencysafeguards,seeSpecifyingDependency CheckingSafeguardsonpage 47.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

59

2 Managing Elements in the Navigation Panel

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

60

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

61

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.

62

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

63

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.

64

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

65

2 Managing Elements in the Navigation Panel

YoucanalsousetheFind Referencescommandtolocateanyunresolvedreferences.An unresolvedreferenceisanelementthatdoesnotexistintheNavigationpanelyetisstill referredtointheservice,ISdocumenttype,orspecificationthatyouselected.The elementmighthavebeenrenamed,moved,ordeleted.Topreventunresolvedreferences, specifythedependencycheckingsafeguards.Formoreinformationaboutthese safeguards,seeSpecifyingDependencyCheckingSafeguardsonpage 47. Note: Developerdoesnotconsiderdocumentreferencestoschematypestobe references,nordoesitconsiderservicesinvokedwithinaJavaservicetobereferences oftheJavaservice.Forexample,ifJavaserviceAinvokesserviceB,andyouinstruct DevelopertofindreferencesforserviceA,serviceBwillnotappearasareferenceof A. 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.

66

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

67

2 Managing Elements in the Navigation Panel

WhenyoueditanISdocumenttype,thechangesaffectanydocumentreferenceand documentreferencelistvariablesdefinedbythatISdocumenttype.Thechangesmight makepipelinereferencesinvalid.Forexample,supposetheinputsignatureforServiceA containsadocumentreferencevariablePOInfobasedontheISdocumenttype 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.

68

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

69

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.

70

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

71

2 Managing Elements in the Navigation Panel

72

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Working with Packages


74 74 88 91

What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing and Retracting Information about Integration Server and Trading Networks Assets .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

73

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,see AdministeringwebMethodsIntegrationServer.

Package Management
YoucanusewebMethodsDevelopertoperformcertainpackagemanagementtasks,such ascreating,copying,anddeletingpackages,ontheIntegrationServer.Whenyou performapackagemanagementtask,allofthefilesandservicesinthepackageare affected. Thefollowingtableidentifiesallofthepackagemanagementtasksthatcanbeperformed usingDeveloperortheIntegrationServerAdministrator.Ifyoucanperformthetask withDeveloper,theSeecolumndirectsyoutoapagewithinthisguideforinstructions. FortasksthatcanonlybeperformedusingtheIntegrationServerAdministrator,theSee columndirectsyoutoAdministeringwebMethodsIntegrationServer. To... Createapackage Activateapackage Copyapackagetoanotherserver Viewdetailsforapackage See... page 76 AdministeringwebMethodsIntegration Server page 79 page 77

74

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

To... Displayspecificpackagesbyfilteringthe PackagesList Documentthepurposeandfunctionofa package Viewthepatchhistoryforapackage

See... AdministeringwebMethodsIntegration Server page 80 page 84and AdministeringwebMethodsIntegration Server page 88 page 81and AdministeringwebMethodsIntegration Server page 82and AdministeringwebMethodsIntegration Server page 83and AdministeringwebMethodsIntegration Server page 86

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 82 page 79and AdministeringwebMethodsIntegration Server AdministeringwebMethodsIntegration Server AdministeringwebMethodsIntegration Server AdministeringwebMethodsIntegration Server AdministeringwebMethodsIntegration Server

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

75

3 Working with Packages

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

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.

76

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 83,ViewingthePatchHistoryforaPackageonpage 84,and IdentifyingPackageDependenciesonpage 86.

Optimizing Lock Checking


IftheDevelopersVersionControlSystemIntegrationfeatureisenabled,Developer mightexhibitslowdowns,errormessages(suchasServerversionhaschangedand Sessionalreadyinuse),andmaystoprespondingcompletelywhenyouexpandalarge element(suchasafolder)oralargepackageintheNavigationpanel.Thiscondition occurswhenDeveloperqueriestheIntegrationServertocheckthelockstateofeach elementinapackage.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

77

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.

78

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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 distributingpackageupdatestodevelopersworkinginlarge,collaborative environments. Forinformationaboutreplicatingpackagesandmanagingreleasesfromwithin IntegrationServerAdministrator,seeAdministeringwebMethodsIntegrationServer. 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 86. Formoreinformationaboutcopyingelementswithinapackage,seeChapter 2, ManagingElementsintheNavigationPanel.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

79

3 Working with Packages

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

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.

80

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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.

Reloading a Package
Sometimes,youneedtoreloadapackageontheservertoactivatechangesthathavebeen madetoitoutsideofDeveloperorDesigner.Youneedtoreloadapackageifanyofthe followingoccurs: 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

81

3 Working with Packages

Deleting a Package
Whenyounolongerneedtheservicesandfilesinapackage,youcandeletethepackage. DeletingapackageremovesthepackageandallofitscontentsfromtheNavigation panel. WhenyoudeleteapackagefromDeveloper,theIntegrationServersavesacopyofthe package.Ifyoulaterwanttorecoverthepackageanditscontents,contactyourserver administrator.OnlyIntegrationServerAdministratoruserscanrecoverapackage.For moreinformationaboutrecoveringpackages,seeAdministeringwebMethodsIntegration Server. Beforeyoudeleteapackage,makesurethat: Otherusersorotherservicesdonotuse(dependon)theservices,templates,IS documenttypes,andschemasinthepackage.YoucanusetheFind Dependents commandtoidentifyotherservicesthataredependentonaserviceinapackagethat youwanttodelete.Formoreinformation,seeFindingDependentsandReferences onpage 64. Allelementsinthepackagethatyouwanttodeleteareunlocked,orlockedbyyou.If thepackagecontainselementsthatarelockedbyothersorsystemlocked,youcannot deletethepackage. 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. Selectthelocationonyourharddrivewhereyouwanttheexportedpackageto reside.ClickSave. ThisexportsthepackagetoaZIPfileandsavesitonyourharddrive.TheZIPfilecan thenbepublishedonanotherserver.

82

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

To export an element 1 2 3 IntheNavigationpanel,selectthefolderorelementthatyouwanttoexport. OntheFilemenu,clickExport.DeveloperdisplaystheExportTodialogbox. Selectthelocationonyourharddrivewhereyouwanttheexportedpartialpackage toreside.ClickSave. ThisexportsthefolderorelementtoaZIPfileandsavesitonyourharddrive.The ZIPfilecanthenbeunzippedintothensdirectoryofapackageontheserver.

Assigning a Version Number to a Package


Youcanassignaversionnumbertoapackagetoidentifydifferentversionsofthe package.Forexample,youmightwanttoassignanewversionnumbertoapackage whenyouaddnewservicestothepackageorafteryoufixbugsinapackage.Youmight findassigningversionnumbersespeciallyhelpfulifyouworkinadevelopment environmentwheremorethanonepersonmakeschangestoapackage. Bydefault,Developerassignstheversionnumber1.0toeachpackagethatyoucreate. Important! Whenyouchangetheversionnumberofapackage,makesurethatyou updatethepackagedependenciesforotherpackagesthatdependontheearlier versionofthispackage. Tip! AssignandchangepackageversionnumbersthroughDeveloperonlywhenthe packagesareinadevelopmentstage.Toavoiddifficultiesinstallingpackagereleases, donotchangeversionnumbersonpackagesyoureceivefromtradingpartners, packagestowhichyousubscribe,orpackagesinstalledwiththeIntegrationServer. To assign a version number to a package 1 2 3 IntheNavigationpanel,selectthepackagetowhichyouwanttoassignaversion number. OntheFilemenu,clickOpen. Intheeditor,clickthepackagesSettingstab.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

83

3 Working with Packages

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

Viewing the Patch History for a Package


Foreachpackage,Developertracksanddisplaysthehistoryofinstalledpatches.Apatch isapartialupgrade,change,orfixtothecontentsofapackage. Youmightwanttocheckapackagespatchhistoryforthefollowingreasons: Toavoidoverwritingtheinstalledpackagewithalowerversionofthesamepackage. Toviewthechangesthatareincludedineachversionofthepackage. ToinformSoftware AGSoftware AGGlobalSupportwhichversionsofpredefined packagesareinstalledonyourIntegrationServer. Whenyouopenapackageintheeditor,thepackagesSettingstabdisplaysthepatch historysincethelastfullreleaseofthepackage.(Afullreleaseofapackageincorporates allpreviouspatchesforthepackage.) 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.

84

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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

Build

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

85

3 Working with Packages

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

86

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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. Important! Makesurethatyoudonotcreatecircularpackagedependencies.For example,ifyouidentifyFinanceUtilasadependentpackagefortheFinance package,donotidentifyFinanceasadependentpackagefortheFinanceUtil package.Ifyoucreatecircularpackagedependencies,neitherpackagewillloadthe nexttimeyoustarttheIntegrationServer.

Removing Package Dependencies


Usethefollowingproceduretoremoveapackagedependencythatisnolongerneeded. Forexample,tocontinuetheexamplefrompage 86,ifyoudeletetheserviceinFinance thatinvokestheserviceinFinanceUtil,thenyouwouldnolongerneedapackage dependencyontheFinanceUtilpackage.Anothercasewhereyouwouldremovethe packagedependencyisifyoumovetheservicesintheFinanceUtilpackageintothe Financepackage.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

87

3 Working with Packages

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. Startupservicesareusefulforgeneratinginitializationfilesorassessingandpreparing (forexample,settinguporcleaningup)theenvironmentbeforetheserverloadsa package.However,youcanuseastartupserviceforanypurpose. Tip! Ifastartupserviceinvokesaserviceinanotherpackage,makesuretoidentifythe otherpackageasapackagedependencyforthepackagecontainingthestartup service.

88

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

89

3 Working with Packages

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. 6 Toaddareplicationservice,dothefollowing: a b UnderReplication Services,click .

IntheEnterInputValuesdialogbox,intheServicefield,dooneofthefollowing:

Typetheservicenameintheformat:folderName:serviceName Click tonavigatetoandselecttheservicethatyouwanttouseasa replicationservice.

c d

ClickOK. Repeatthesestepsforeachserviceyouwanttoaddasareplicationservice.

90

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

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 .

Publishing and Retracting Information about Integration Server and Trading Networks Assets
YoucanpublishandretractinformationaboutIntegrationServerandTradingNetworks assetstoasharedlibraryorregistrythatresidesinCentraSite.Bypublishingthis informationormetadata,youmaketheseassetsavailabletootherCentraSiteusers. ForIntegrationServer,youcanpublishandretractinformationaboutthefollowing assets:packages,folders,adapterservices,adapternotifications,flowservices,Java services,Cservices,specifications,documenttypes,Webservicedescriptors,andXSLT services. Note: IntegrationServerpublishes/retractsWebserviceconnectorsaspartof publishing/retractingaconsumerWebservicedescriptor. ForTradingNetworks,youcanpublishandretractinformationaboutTNdocument types.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

91

3 Working with Packages

Publishing Metadata about Integration Server and Trading Networks Assets


KeepthefollowingpointsinmindwhenpublishingmetadatatoCentraSiteforISandTN assets: BeforeyoucanpublishmetadataaboutISassetsandTNdocumenttypes,your IntegrationServeradministratormustconfigureIntegrationServertoconnectto CentraSite.RefertoAdministeringwebMethodsIntegrationServerforinstructionson configuringIntegrationServertoconnecttoCentraSite. EveryuserwhopublishesinformationaboutISassetsandTNassetsviaIntegration ServerandDevelopersharesthesameCentraSitecredentials.Thisisbecausethe configurationisspecifiedfortheIntegrationServerandnotperuser. TopublishmetadataaboutanIntegrationServerasset,youselectthepackagethat containstheassetwhosemetadatayouwanttopublish.Developerwillpublish metadatafortheentirepackage. TopublishmetadataaboutTradingNetworksassets,youselectTrading Networks Assets.DeveloperwillpublishmetadataforallTNdocumenttypesavailableonthe IntegrationServertowhichDeveloperisconnected. WhenIntegrationServerpublishesapackagethatcontainsWebservicedescriptor, CentraSitecreatesanESBWSDescriptorassetandaServiceasset.Tomakethe operationsinaproviderWebservicedescriptoravailabletootherconsumersasa Webservice,publishtheISservicesusedasoperationsintheWebservicedescriptor aswell. AproviderWebservicedescriptorcanbepublishedtoCentraSitetwodifferentways:

BypublishingthepackagethatcontainstheproviderWebservicedescriptorvia metadatapublishing. BypublishingtheproviderWebservicedescriptorthroughtheUDDIRegistry view.

IfyouwanttopublishISassetsinadditiontowebservices,publishtheproviderWeb servicedescriptorbypublishingtheentirepackage.Ifyouexpecttopublishonlyweb servicestoCentraSite,publishtheindividualproviderWebservicedescriptor throughtheUDDIRegistryview.Typically,userschooseonewayortheotherfor publishingWebserviceassets.Software AGdoesnotrecommendusingamixtureof publishingmethods. Onlyonemetadataoperationcanrunatatime.Ifyoutrytosubmitapublication requestwhilearetractionorpublicationrequestisalreadyrunning,youwillreceive theerrorOperation already in progressandyouwillhavetoresubmittherequest later.

92

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

To publish information about assets 1 2 OntheToolsmenu,selectMetadata > Publish > Execute. InthePublishMetadatadialogbox:

TopublishmetadataaboutIntegrationServerassets,selectoneormorepackages. TopublishmetadataaboutTradingNetworksassets,selectTrading Networks Assets.

IfyouwantIntegrationServertoautomaticallypublishinformationaboutpackages uponwhichselectedpackagesdepend,selecttheAuto-select package dependencies checkbox. ClickOK. Toviewthestatusofthepublicationrequest,ontheToolsmenu,clickMetadata > Publish > Status.

Retracting Published Metadata about Integration Server and Trading Networks Assets
IfyoulaterdecideyouwanttoremoveanassetfromCentraSite,youcanretractit. KeepthefollowingpointsinmindwhenretractingmetadataforISandTNassets: ForanIntegrationServerasset,youmustretractthepackageinwhichtheasset resides. ForTradingNetworksassets,youmustretractallTNdocumenttypes. Youcannotretractapublishedassetthatisreferencedbyanotherpublishedasset untiltheassetthatestablishedthereferenceisretracted.Forexample,supposethat youpublishaprocess(processA),thatusesanISservice(serviceA).Then,you publishthepackage(packageA)thatcontainsserviceA.BecauseprocessAdepends onanassetinpackageA,youcanonlyretractpackageA(andanyofitscontents)after youretractprocessA.IfyouchangeprocessAsothatitnolongerreferencesserviceA andrepublishprocessA,youcanretractpackageA. Onlyonemetadataoperationcanrunatatime.Ifyoutrytosubmitapublication requestwhilearetractionorpublicationrequestisalreadyrunning,youwillreceive theerrorOperation already in progressandyouwillhavetoresubmittherequest later. Note: BeforeuninstallingIntegrationServer,retractallpublishedISandTNassets. ThiswillpreventorphanedassetsinCentraSite.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

93

3 Working with Packages

To retract information about assets 1 2 OntheToolsmenu,selectMetadata > Retract > Execute. IntheRetractMetadatadialogbox:

ToretractmetadataaboutIntegrationServerassets,selectoneormorepackages. ToretractmetadataaboutTradingNetworksassets,selectTrading Networks Assets.

3 4

ClickOK. Toviewthestatusoftheretractionrequest,ontheToolsmenu,clickMetadata > Retract > Status.

Checking the Status of Publication and Retraction Requests


AfteryousubmitarequesttopublishorretractinformationaboutIntegrationServeror TradingNetworksassets,youcancheckthestatusoftherequest. To check the status of a publication request OntheTools menu,selectMetadata > Publish > Status. To check the status of a retraction request OntheToolsmenu,selectMetadata > Retract > Status.

Status Information for Publication and Retraction Requests


Forbothpublicationandretractionrequests,Developerdisplaysastatusscreenthat containsthefollowinginformation: Field Name Description Ifapackagewasselectedformetadatapublicationorretraction,this fielddisplaysthepackagename. IfTrading Networks Assetswasselectedformetadatapublicationor retraction,thisfielddisplaysTN Assets. Assets Thetotalnumberofassetsbeingprocessed.Thisvaluewillnotbe displayeduntilalltheassetsforthegivenpackageorallTNdocument typeshavebeencounted.

94

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

3 Working with Packages

Field Status

Description Oneofthefollowingstates:
Starting Counting Counted

IntegrationServerisstartingtherequest.Thisis alwaystheinitialstatewhenarequestissubmitted. IntegrationServeriscountingthenumberofassetsin thepackageorthenumberofTNdocumenttypes. IntegrationServerhascompletedcountingthenumber ofassetsinthepackageorthenumberofTN documenttypes.Thetotalnumberisdisplayedinthe Assetscolumn. IntegrationServerisextractingthemetadatafor selectedassets. Forpublicationrequestsonly:IntegrationServeris sendingthemetadatatoCentraSite. Forpublicationrequests,IntegrationServerhas finishedsendingthemetadatatoCentraSite. Forretractionrequests,IntegrationServerhasfinished retractingthemetadatafromCentraSite.

Extracting Publishing Complete

Thefollowingsummaryfieldsaredisplayedatthebottomofthescreen: Field Status Assets Duration Description Theoverallstatusofthemostrecentpublicationorretraction request. Thetotalnumberofassetsprocessedinthemostrecentpublication orretractionrequest. Thetime(inhh:mm:ss)spentexecutingthemostrecentpublication orretractionrequest.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

95

3 Working with Packages

96

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Locking and Unlocking Elements


98 100 104 109 111

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

97

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,seeStoringServicesinaVersionControlSysteminthe Software AG_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.

98

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

4 Locking and Unlocking Elements

ElementsareshowninthefollowingwaysinDeveloper: Element Status Notlocked Lockedbyyou Lockedbyanotheruser Lockedbythesystem Can I edit? No Yes No No How do I gain rights to edit? ClickFileLock for Edit. N/A 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 103andViewinganElementsCorrespondingServerFileson page 108.

When Do I Lock an Element?


Youlockanelementwhenyouwanttomakechangestotheelement.Fordetails,see LockingElementsonpage 100.

When Do I Unlock an Element?


Youunlockanelementaftermakingyourchangesandsavingthosechangestotheserver. Itisimportanttounlocktheelementsyouaredonewithsothatotherusersontheserver canaccessthem.Fordetails,seeUnlockingElementsonpage 104. Ifyouwanttoautomaticallyunlockanelementaftersavingit,youcanenableasettingon theOptionsdialogbox.Fordetails,seeAutomaticallyUnlockingElementsAfter Savingonpage 108.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

99

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

100

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

4 Locking and Unlocking Elements

WhenyoulockaJavaorC/C++service,DeveloperlocksallotherJavaorC/C++ serviceswithinthefolder.Fordetails,seeLockingJavaandC/C++Serviceson page 101. 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 109. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

101

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,youcansystemlockanelementbyusingtheservers filesystemtomaketheelementssupportingserverfilesreadonly.Ifyoudonotknow thenamesofthefilesthatcorrespondtoaparticularelement,usetheLock Status command.Fordetails,seeViewinganElementsCorrespondingServerFileson page 108.Usually,asystemlockisnotreflectedinwebMethodsDeveloperorthe IntegrationServerAdministratoruntilyoureloadthepackageinwhichtheelement resides. Important! Beforeyousystemlockanelement,alwaysverifythatitisnotlockedbya userontheIntegrationServer.Ifanelementbecomessystemlockedwhileauseris editingit,theuserwillnotknowuntilheorshetriestosavechangestotheelement.If thisoccurs,maketheelementscorrespondingfileswritableontheserver.Afterthisis done,theusercansavehisorherchangestotheelement. Note: System locking is not supported if you are running IntegrationServer as root on

a Unix system.

102

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

4 Locking and Unlocking Elements

Viewing the Status of Locked Elements


Thelockstatusofanelementtellsyouifanelementisavailableforlocking,andifnot, whoownsthelockandwhentheylockedit.Youcanviewthestatusofalockedelement toseewhoownsthelockoryoucanviewalistofallelementsforwhichyouownthe lock. 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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

103

4 Locking and Unlocking Elements

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

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

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

104

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

4 Locking and Unlocking Elements

IfaJavaorCserviceinafolderhasunsavedchanges,youwillnotbeabletounlock otherJavaorCserviceswithinthatfolder.Savethechangesandthenunlockthe services. Whenyouunlockanadapternotification,Developeralsounlocksitsassociated publishabledocumenttype.Youcannotdirectlyunlockthepublishabledocument typeassociatedwithanadapternotification. Youcannotunlockalistenerorconnectionelement.


.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

105

4 Locking and Unlocking Elements

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. Locked Elements screen
localhost means the machine on which the server is running

ClickUnlock Elements.Thefollowingscreenappears. Unlock Selected Elements screen

106

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

4 Locking and Unlocking Elements

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

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 108. Ontheserversfilesystem,removethereadonlypropertiesfromthefilesthat correspondtotheelementtomakethefileswritable. ReloadthepackageontheIntegrationServerthatcontainstheelement.Theupdated statusisreflectedintheIntegrationServerAdministrator.RefreshtheNavigation panelinDevelopertoviewtheupdatedstatus.

2 3

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

107

4 Locking and Unlocking Elements

Important! Ifyouaccidentallyappliedasystemlocktoanelementthatwasalready lockedbyanotheruser,removethesystemlockbutDO NOThavetheuserreloadthe packageinwebMethodsDeveloper.(ReloadingthepackageinDeveloperwill discardtheiredits.)Theusercanthensavetheelementwithoutlosingthechangeshe orshemadetoitwhileyouhadtheelementsystemlocked.

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,itmaynotbethebestoptionifyousaveperiodicallywhile editinganelement. Important! WhenanIntegrationServerhastheVCSIntegrationfeatureenabled,the Automatically unlock upon saveoptionmust be disabled.

108

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

109

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.

110

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

111

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! Donotperformdevelopmentworkinaclusteredenvironment.Basic namespacelockingandtheWmVCSpackagearenotsupportedacrossIntegration Serversinacluster. 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).

112

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Assigning and Managing Permissions


114 117 120 121 122

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

113

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. ExecutecontrolswhetherausercanexecuteaserviceoraWebservicedescriptor. Formoredetailsaboutthesetypesofaccess,seeAdministeringwebMethodsIntegration Server.

What Happens When a Client Runs a Service with ACLs?


WhenaclientrequeststhatwebMethodsIntegrationServerinvokeaservice,theserver checkstheACLassignedtotheservice.Iftheclientisamemberofanallowedgroupand isnotamemberofadeniedgroup,theserverexecutestheservice.Iftheclientisnota memberofanallowedgroup,theserverdeniestherequesttoinvoketheserviceand stopsexecuting.

114

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

5 Assigning and Managing Permissions

Bydefault,whenaclientrequestsaservice,webMethodsIntegrationServerchecksonly theACLoftheexternallyinvokedservice(theservicerequesteddirectlybytheclient). TheserverdoesnotchecktheACLsofanyoftheinternallyinvokedservices(those servicesinvokedbytheexternallyinvokedservice).However,youcansetupthesecurity settingsforaservicesothatwebMethodsIntegrationServercheckstheACLassignedto theserviceeverytimeitisinvoked,whetherdirectlybyaclientorbyanotherservice.For details,seeThePermissionsPropertiesonpage 118. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

115

5 Assigning and Managing Permissions

Stage
3

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

Note: Ifthesecuritysettingsforthe Purch:LogPO,Purch:CreditAuth,orPurch:SendPO servicesspecifythatACLcheckingoccurseverytimetheserviceisinvoked(Enforce execute ACLoptionissettoAlways),webMethodsIntegrationServerwouldperform ACLcheckingwhentheexternallyinvokedservice(Purch:SubmitPO)invokedthese services.FormoreinformationaboutrequiringACLchecking,seeAssigningACLs toElementsonpage 117. 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, seeAdministeringwebMethodsIntegrationServer.

How Do I Create an ACL?


YoucreateACLsusingtheIntegrationServerAdministrator.Fordetails,see AdministeringwebMethodsIntegrationServer.

116

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

5 Assigning and Managing Permissions

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,seeAdministering webMethodsIntegrationServer. IntheNavigationpanel,clickthepackageorfoldertowhichyouwanttoassignan ACL. OntheFilemenu,clickOpen. Intheeditor,clickthetitlebarofthepackageorfoldertogiveitthefocus. InthePermissionscategoryofthePropertiespanel,selecttheACLsthatyouwantto assignforeachlevelofaccess.Fordetails,seeThePermissionsPropertieson page 118. Important! ForList,Read,andWriteaccess,youcanonlyassignACLsofwhichyou areamember.IfyoucannotassignanACLtoanelementforList,Read,orWrite access,youprobablyarenotamemberofausergroupintheAllowedlistofthat ACL.Toverify,usetheToolsACL Informationcommand.Toobtainaccesstoan ACL,contactyourserveradministrator. 6 Savetheelement.Ifanerrormessageappears,checktomakesurethatyouarea memberofeachACLthatyouassignedtotheelement.
To assign an ACL to other elements in the Navigation panel
To

2 3 4 5

MakesurethattheACLyouwanttoassignexistsontheIntegrationServer.Ifnot, createtheACLintheIntegrationServerAdministrator.Fordetails,seeAdministering webMethodsIntegrationServer. OpentheelementtowhichyouwanttoassignanACL.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

117

5 Assigning and Managing Permissions

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

Savetheelement.Ifanerrormessageappears,checktomakesurethatyouarea memberofeachACLthatyouassignedtotheelement.

The Permissions Properties


YouassignanACLtoanelementinthePermissionscategoryofthePropertiespanel. Dependingontheelementyouselect,certainaccesslevelsaredisplayed.Forexample, forapackage,youcanonlysetListaccess.Fordetailsaboutthedifferentlevelsofaccess availableforelements,seeAdministeringwebMethodsIntegrationServer. TheACLsassignedtoanelementaremutuallyexclusive;thatis,anelementcanhave differentACLsassignedforeachlevelofaccess.Forexample,thefollowingelementhas theDevelopersACLassignedforReadaccessandtheAdministratorsACLassignedfor Writeaccess. 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

Description UsersintheAllowedlistofthisassignedACLcanseethattheelement existsandviewtheelementsmetadata(input,output,etc.). UsersintheAllowedlistofthisassignedACLcanviewthesourcecode andmetadataoftheelement. UsersintheAllowedlistofthisassignedACLcanlock,edit,rename, anddeletetheelement. UsersintheAllowedlistofthisassignedACLcanexecutetheservice. ThislevelofaccessonlyappliestoservicesandWebservicedescriptors.

118

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

5 Assigning and Managing Permissions

Field / Button Enforce execute ACL

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

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

119

5 Assigning and Managing Permissions

Default ACLs and Inheritance


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

Viewing ACL Information on a Server


YoucanviewtheusersandgroupsthatmakeuptheACLsonaserverbyusingthe ToolsACL Informationcommand.TheACLInformationdialogboxliststheACLs containedontheIntegrationServertowhichyouareconnected.Thisinformationisread only;toeditACLs,users,andgroups,usetheIntegrationServerAdministrator. 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]

120

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

5 Assigning and Managing Permissions

Field Resulting Users for [ACL]

Description ThenamesofusersthattheACLauthorizes,giventhecurrent settingsintheAllowedandDeniedlists.Theserverbuildsthislistby lookingatthegroupstowhicheachuserbelongsandcomparing thattothegroupstowhichtheACLallowsordeniesaccess.For detailsonhowtheserverdeterminesaccess,seeAdministering webMethodsIntegrationServer.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

121

5 Assigning and Managing Permissions

TotestaservicebysendinganXMLfiletoaservice,youmusthaveReadaccesstothe service. Tosetabreakpointinaservice,youmusthaveReadaccesstotheservice.

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,seeAdministeringwebMethodsIntegrationServer. 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 109inChapter 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.

122

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

5 Assigning and Managing Permissions

I receive an exception when I try to lock an element. Theelementmaybelockedbysomeoneelse,systemlocked(markedreadonlyonthe server),oryoumaynothaveWriteaccess.RefreshtheNavigationpanel.Ifalockisnot shownbutyoustillcannotlocktheelement,reloadthepackage.Inaddition,makesure 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

123

5 Assigning and Managing Permissions

124

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Building Flow Services


126 130 131 133 138 141 151 154 157 166

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 and Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Service Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

125

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.

126

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

What Is a Flow Step?


Aflowservicecontainsflowsteps.Aflowstepisabasicunitofwork(expressedinthe webMethodsflowlanguage)thatwebMethodsIntegrationServerinterpretsandexecutes atruntime.ThewebMethodsflowlanguageprovidesflowstepsthatinvokeservicesand flowstepsthatletyoueditdatainthepipeline. webMethodsflowlanguagealsoprovidesasetofcontrolstepsthatallowyoutodirect theexecutionofaflowserviceatruntime.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 200. Executesaspecifiedservice.Formoreinformationaboutthis step,seeTheINVOKESteponpage 173.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

127

6 Building Flow Services

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

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.

128

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

129

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 133. Mapping pipeline data. Duringthisstage,yourouteinputandoutput variablesbetweenservicesthatareinvokedintheflow.Forinformation aboutthisstage,seeChapter 8,MappingDatainaFlowService. Specifying the run-time parameters.Duringthisstage,youassignparameters thatconfiguretheruntimeenvironmentforthisservice.Forinformation aboutthisstage,seeSpecifyingRunTimeParametersonpage 141. Formatting service output.Duringthisstageyoucancreateanoutput templatetoformattheserviceoutput.Forinformationaboutthisstage, seeAssigninganOutputTemplatetoaServiceonpage 138orreferto 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.

130

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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 76. 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 45.For informationaboutACLpermissions,seeChapter 5,AssigningandManaging Permissions. Oncethepackageandfolderareinplace,usetheFileNewcommandtostarttheprocess ofcreatinganewservice.Fordetails,seeCreatingNewElementsonpage 45.

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,seetheLoadandQueryServicesDevelopersGuide. Receive an XML Document AutomaticallygenerateaservicethatreceivesanXMLnodeas input.IfyouspecifytheformatbyprovidingaDTDorXMLSchema definition,webMethodsDevelopermapstheincomingdocumentto itscorrespondingISdocumenttypestructure.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

131

6 Building Flow Services

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

Inserting Flow Steps


Flowstepscallpreviouslybuiltservicesanddirecttheflowofdatawithinaflowservice. Youcaninsertflowstepsintoaflowserviceusingthebuttonsatthetopoftheeditor.For moreinformation,seeChapter 7,InsertingFlowSteps. To insert a/an... INVOKEstep MAPstep BRANCHstep LOOPstep REPEATstep SEQUENCEstep EXITstep Click this button...

132

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

133

6 Building Flow Services

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

134

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

135

6 Building Flow Services

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 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 133. Skiptherestofthisprocedure. Important! Whenaspecificationisassignedtoaservice,youcannotadd,delete,or modifythedeclaredvariablesusingtheservicesInput/Outputtab.

136

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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.

Foreachinputoroutputvariablethatyouwanttodefine,dothefollowing: a b c d e Selectthehalfofthe Input/Outputtab(InputorOutput)whereyouwanttodefinethe variablebyclickinganywhereinthathalfslargewhitetextbox. Click onthetoolbarandselectthetypeofvariablethatyouwanttodefine.

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

Ifyouwanttoenteranynotesorcommentsabouttheinputandoutputparameters, typeyourcommentsontheCommentstab.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

137

6 Building Flow Services

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. To assign an output template to a service 1 2 Opentheservicetowhichyouwanttoassignanoutputtemplate. Intheeditor,clicktheservicestitlebartogivetheservicethefocus.

138

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

IntheOutput templatecategoryofthePropertiespanel,dooneofthefollowingto updatetheNamefield:

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

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 aboutcreatinganoutputtemplate,seetheDynamicServerPagesandOutputTemplates DevelopersGuide.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

139

6 Building Flow Services

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.

ClickSave. Important! AftereditingatemplateinDeveloper,donotedititoutsideofDeveloper. Thiswillaffecttheinterpretationoftheencodingsettingsandmayresultin charactersbeinglostormisinterpreted.

140

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Specifying Run-Time Parameters


Asadeveloperofaservice,youcanusethePropertiespaneltospecifythefollowing serviceparameters: State of a service.Youcanmaintainwhetherornotyouwanttheservertotreatitasa statelessserviceatruntime. Caching of service results.Youcancacheelementstoreducememoryusagein Developer.Fordetails,seeTocacheelementsonpage 70. Execution locale of a service.YoucansetthetypeoflocaleinwhichtheIntegration Serverexecutesatruntime. Creating a URL alias for a service.YoucancreateanaliasforthepathportionoftheURL usedtoinvokeaservice. Saving and restoring of the pipeline.Youcansavethepipelineorrestoreapreviously savedpipelineatruntime. 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)doesnotneedtohaveitssession objectmaintainedwhenitisfinishedexecuting.Forbestperformance,usestateful servicesifyourIntegrationServerreceivesrequestsfromrepeatingclients.Theclientcan connecttoIntegrationServer,beauthenticatedjustonce,andthenissuemanyservice invocationsduringthesamesession.Usestatelessservicesifclientstypicallysenda singleinvocationrequesttoIntegrationServeratatime.Usingastatelessservice preventsthecreationofsessionsthatwillsitunused,takingupresourcesinIntegration Server.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

141

6 Building Flow Services

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.

Configuring a Services Use of Cache


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

142

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

143

6 Building Flow Services

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.

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.

144

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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.

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:

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

145

6 Building Flow Services

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... 4 To... UsetheserversdefaultJVMlocale. Usetheclientlocale. Usenolocalepolicy. UsetheneutralorPOSIXlocale. Useaspecificlocale. Defineacustomlocale.

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.

146

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Setting Up URL Aliases for Services


UsingaURLaliasforaserviceisconvenientbecauseitsavesyoufromspecifyingfull pathinformationfortheserviceeverytimeyouhavetoentertheserviceURL.Also,ifa serviceURLhasanalias,youcanupdatethepathinformationfortheservicewithout havingtomodifythealias.Anotherbenefittousingaliasesistheaddedsecurity;they preventtheexternalworldfromseeingtheservicenamesinaURL. WhenyoucreateaURLalias,youspecifyanaliasforthepathportionoftheURLusedto invokeaservice.ThepathportionoftheURLconsistsoftheinvokedirectiveandthe fullyqualifiedservicename. YoucancreateURLaliasesforservicesfromDeveloperandfromIntegrationServer. CreateanaliasfromIntegrationServerifyouwanttoassignaliasestoresourcesother thanservices,orifyouwanttoassignmorethanonealiastoaresource.SeeAdministering webMethodsIntegrationServerformoreinformation. Example
1 2

http://IS_server:5555/invoke/folder.subFolder/serviceName

Item
1 2

Description IdentifiesthewebMethodsIntegrationServeronwhichtheserviceyouwant toinvokeresides. SpecifiesthepathportionoftheURL,whichincludestheinvokedirective invoke.Thepathalsoidentifiesthefolderinwhichtheserviceresidesand thenameoftheservicetoinvoke.Separatesubfolderswithperiods.These fieldsarecasesensitive.Besuretousethesamecombinationofupperand lowercaselettersasspecifiedinthefoldernameonwebMethodsIntegration Server.

TocreateanaliasforaserviceURL,usetheHTTP URL aliaspropertyintheProperties panel.WhenyouspecifyanaliasintheHTTP URL aliaspropertyandsavetheservice, IntegrationServercreatesanHTTPpathaliasfortheserviceURL.Thetargetofthealias isthepaththatinvokestheservice.Thepathaliasisthestringthatyouenteredinthe propertyfield. Forexample,ifthenameoftheserviceisfolder.subFolder:serviceName,thenthepathto invoketheserviceisinvoke/folder.subFolder/serviceName.IfyouentertestintheHTTP URL aliaspropertyandsavetheservice,thenthetwofollowingURLswillpointtothe sameservice: http://IS_server:5555/invoke/folder.subFolder/serviceName http://IS_server:5555/test

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

147

6 Building Flow Services

Whencreatingapathaliasforaservice,keepthefollowinginmind: Whenyouadd,edit,ordeleteanHTTP URL aliaspropertyinaservice,thepropertyis automaticallyupdatedontheIntegrationServerwhentheserviceissaved. IntegrationServerstorestheHTTP URL aliasinformationinthenode.ndffileofthe service.Becausethepropertyisencodedinthenode.ndffile,itispropagatedacross serversthroughpackagereplication. URLaliasesforservicesaresavedinmemoryontheIntegrationServer.Theserver checksforURLaliasesbeforeprocessingHTTPGETorPOSTrequests. WhenspecifyingthealiasURL,youmustspellitexactlyasitisdefinedontheserver. AliasURLsarecasesensitive.

Creating a Path Alias for a Service


UsetheHTTP URL aliaspropertyinthePropertiespaneltocreateapathaliastousewhen invokingtheserviceinaURL. To create an alias for a service URL 1 2 3 Opentheservicethatyouwanttoconfigure. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,nexttotheHTTP URL aliasproperty, enteranaliasstringfortheURLthatwillinvoketheservice. Important! DonotusereservedcharactersintheURLaliasstring.Aliasstringsthat containreservedcharactersareinvalidandwillnotwork. 4 OntheFilemenu,clickSave.

148

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Using the Pipeline Debug Property


YouusethePipeline Debugpropertytosaveandrestorethepipelineatruntime.The abilitytosaveandrestorethepipelineforaserviceishelpfulwhenyouaretestingand debuggingtheservice. Important! ThePipelineDebugoptionsyouselectcanbeoverwrittenatruntime bythevalueofthewatt.server.pipeline.processorproperty,setintheserver configurationfile.Thispropertyspecifieswhethertogloballyenableordisable thePipelineDebugfeature.ThedefaultenablesthePipelineDebugfeatureon aservicebyservicebasis.Formoreinformationonsettingpropertiesinthe serverconfigurationfile,seeAdministeringwebMethodsIntegrationServer. Formoreinformationabouttestinganddebuggingservicesandtolearnaboutothertools andmethodsyoucanuse,seeChapter 11,TestingandDebuggingServices.

Using the Pipeline Debug Property to Save the Service Pipeline


YouusethePipeline Debugpropertytospecifywhetherornotyouwanttheserverto automaticallysavethepipelinefortheserviceatruntime.IfyousetPipeline DebugtoSave, webMethodsIntegrationServersavestheentirecontentsofthepipelinetoafilejust beforetheserviceexecutes. To save the service pipeline 1 2 3 Opentheservicethatyouwanttoconfigure. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,nexttothePipeline Debugproperty, selectSave. Whenyouruntheservice,thecontentsofthepipelinearesavedtoafileon webMethodsIntegrationServer.ThefileissavedasfolderName.serviceName.xmlinthe IntegrationServer_directory\pipelinedirectory.Ifthefiledoesnotexist,theservice createsit.Ifthefilealreadyexists,theserviceoverwritesit.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

149

6 Building Flow Services

Using the Pipeline Debug Property to Restore the Service Pipeline


YouusethePipeline Debugpropertytospecifywhetherornotyouwanttheserverto automaticallyrestorethepipelinefortheserviceatruntime.Whenyourestorethe servicepipelineusingthisproperty,webMethodsIntegrationServereithermergesor overwritesthepipelineusingthecontentsfromapreviouslysavedpipelinefile. To restore the service pipeline 1 2 3 Opentheservicethatyouwanttoconfigure. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. IntheRuntimecategoryofthePropertiespanel,nexttothePipeline Debugproperty, selectoneofthefollowingoptions: Select... Restore (Override) Restore (Merge) To... Restorethepipelinefromafilewhentheserviceexecutes. Mergethepipelinewithonefromafilewhentheservice executes. Whenthisoptionisselectedandtheinputparametersinthefile matchtheinputparametersinthepipeline,thevaluesdefined inthefileareusedinthepipeline.Ifthereareinputparameters inthepipelinethatarenotmatchedinthefile,theinput parametersinthepipelineremaininthepipeline. Whentheserviceexecutes,theserverloadsthepipelinefile, folderName.serviceName.xml,fromtheIntegrationServer_directory\pipelinedirectory. Note: Theserverwillthrowanexceptionatruntimeifthepipelinefiledoesnot existorcannotbefound.Tolearnhowtosavetheservicepipelineusingthe PipelineDebugproperty,seeUsingthePipelineDebugPropertytoSavethe ServicePipelineonpage 149.

150

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

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.

Note: Ifserviceauditingisalsoconfiguredfortheservice,theIntegrationServeradds anentrytotheservicelogforeachfailedretryattempt.Eachoftheseentrieswillhave astatusofRetriedandanerrormessageofNull.However,iftheIntegration Servermakesthemaximumretryattemptsandtheservicestillfails,thefinalservice logentryfortheservicewillhaveastatusofFailedandwilldisplaytheactualerror message.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

151

6 Building Flow Services

About the Maximum Retry Period


TheIntegrationServerusesthesameserverthreadfortheinitialserviceexecutionand thesubsequentretryattempts.TheIntegrationServerreturnsthethreadtotheserver threadpoolonlywhentheserviceexecutessuccessfullyortheretryattemptsare exhausted.Topreventtheexecutionandreexecutionofasingleservicefrom monopolizingaserverthreadforalongtime,theIntegrationServerenforcesamaximum retryperiodwhenyouconfigureserviceretryproperties.Themaximumretryperiod indicatesthetotalamountoftimethatcanelapseiftheIntegrationServermakesthe maximumretryattempts.Bydefault,themaximumretryperiodis15,000milliseconds (15seconds). Whenyouconfigureserviceretry,theIntegrationSerververifiesthattheretryperiodfor thatservicewillnotexceedthemaximumretryperiod.TheIntegrationServer determinestheretryperiodfortheservicebymultiplyingthemaximumretryattempts bytheretryinterval.Ifthisvalueexceedsthemaximumretryperiod,Developerdisplays anerrorindicatingthateitherthemaximumattemptsortheretryintervalneedstobe modified. 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.

152

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 152. To configure service retry 1 2 3 Opentheserviceforwhichyouwanttoconfigureserviceretry. Intheeditor,clicktheservicestitlebartogivetheservicethefocus. UndertheRetry on ISRuntimeExceptioncategoryofthePropertiespanel,intheMax attemptsproperty,specifythenumberoftimestheIntegrationServershouldattempt toreexecutetheservice.Thedefaultis0,whichindicatesthattheIntegrationServer doesnotattempttoreexecutetheservice. IntheRetry intervalproperty,specifythenumberofmillisecondstheIntegration Servershouldwaitbetweenretryattempts.Thedefaultis0milliseconds,which indicatesthattheIntegrationServerreexecutestheserviceimmediately. OntheFilemenu,clickSave. Tip! Youcaninvokethepub.flow:getRetryCountservicetoretrievethecurrentretrycount andthemaximumspecifiedretryattempts.Formoreinformationaboutthisservice, seethewebMethodsIntegrationServerBuiltInServicesReference.Formoreinformation aboutbuildingaservicethatretries,seeConfiguringServiceRetryonpage 151.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

153

6 Building Flow Services

Assigning Universal Names to Services and Document Types


EveryserviceanddocumenttypeonawebMethodsIntegrationServerhasauniversal nameinadditiontoitsregularwebMethodsname.Auniversalnameisauniquepublic identifierusedtoreferenceaserviceordocumenttypeonaIntegrationServer. Auniversalnamehastwoparts:anamespacenameandalocalname. ThenamespacenameisaqualifierthatdistinguishesawebMethodsserviceor documenttypefromotherresourcesontheInternet.Forexample,theremightbe manyresourceswiththenameAcctInfo.AnamespacenamedistinguishesoneAcctInfo resourcefromanotherbyspecifyingthenameofthecollectiontowhichitbelongs, similartothewayinwhichastateorprovincenameservestodistinguishcitieswith thesamename(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.ManywebMethodsusersuseaservicesordocumenttypes unqualifiednameasitslocalname.Underthisscheme,aservicenamed gl.journals:closeGLwouldhavealocalnameofcloseGL. LocalnamesfollowthesameconstructionrulesasNCNamesinXML.Alocalname canbecomposedofanycombinationofletters,digits,orthefollowingsymbols: . _ (period) (dash) (underscore)

Additionally,thelocalnamemustbeginwithaletteroranunderscore.Thefollowing areexamplesofvalidlocalnames: addCustOrder authorize_Level1 gnrent ForspecificrulesrelatingtoNCNames,seeNCNamedefinitionintheNamespaces inXMLspecificationat http://www.w3.org/TR/1999/RECxmlnames19990114.

154

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Auniversalnamecanbeeitheranexplicitoranimplicituniversalname. An explicit universal name isauniversalnamethatyouassigntoaserviceordocument typebyspecifyingbothanamespacenameandalocalnameinthePropertiespanel. An implicit universal nameisautomaticallyderivedfromthenameoftheserviceor documenttypeitself,anditactsastheuniversalnamewhenanexplicituniversal namehasnotbeenspecified.Theserverderivesanimplicitnameasfollows:

Thenamespacenameistheliteralstringhttp://localhost/followedbythefully qualifiednameofthefolderinwhichtheserviceordocumenttyperesidesonthe IntegrationServer. Thelocalnameistheunqualifiednameoftheserviceordocumenttype.

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 Opentheserviceordocumenttypewhoseuniversalnameyouwanttoassign,edit,or view. Intheeditor,clicktheservicesordocumenttypestitlebartogivetheserviceor documenttypethefocus. Ifyouwanttoassignoreditauniversalname,specifythefollowingintheUniversal NamecategoryofthePropertiespanel: In this field... Namespace name Local name Specify... TheURIthatwillbeusedtoqualifythenameofthisserviceor documenttype.YoumustspecifyavalidabsoluteURI. Anamethatuniquelyidentifiestheserviceordocumenttype withinthecollectionencompassedbyNamespace name.The namecanbecomposedofanycombinationofletters,digits,or theperiod(.),dash()andunderscore(_)characters. Additionally,itmustbeginwithaletterortheunderscore character. Note: ManywebMethodsusersusetheunqualifiedportionofthe servicenameordocumenttypeasthelocalname.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

155

6 Building Flow Services

OntheFilemenu,clickSave. Note: Ifyoumoveaserviceordocumenttype,orafoldercontainingaserviceor documenttype,Developerretainstheservicesordocumenttypesexplicituniversal name.Ifyoucopyaserviceordocumenttype,orafoldercontainingaserviceor documenttype,Developerdoesnotretaintheexplicituniversalname. To delete a universal name

1 2 3 4

Opentheserviceordocumenttypewhoseuniversalnameyouwanttodelete. Intheeditor,clicktheservicesordocumenttypestitlebartogivetheserviceor documenttypethefocus. IntheUniversal NamecategoryofthePropertiespanel,clearthesettingsinthe Namespace nameandLocal namefields. OntheFilemenu,clickSave.

156

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Configuring Service Auditing


ServiceauditingisafeatureintheIntegrationServerthatyoucanusetotrackwhich servicesexecuted,whenservicesstartedandcompleted,andwhetherservicessucceeded orfailed.Youperformserviceauditingbyanalyzingthedatastoredintheservicelog. Theservicelogcancontainentriesforservicestart,serviceend,andservicefailure.The servicelogcanalsocontainacopyoftheinputpipelineusedtoinvoketheservice.Atrun time,servicesgenerateauditdataatpredefinedpoints.TheIntegrationServercaptures thegeneratedauditdataandstoresitintheservicelog.Iftheservicelogisstoredina database,youcanreinvokeservicesusingthewebMethodsMonitor. Note: WhentheIntegrationServerlogsanentryforaservice,thelogentrycontains theidentityoftheserverthatexecutedtheservice.TheserverIDinthelogentry alwaysusestheIntegrationServerprimaryport,evenifaserviceisexecutedusing another(nonprimary)IntegrationServerport. EachservicehasasetofauditingpropertieslocatedintheAuditcategoryontheservices Propertiespanel.Thesepropertiesdeterminewhenaservicegeneratesauditdataand whatdataisstoredintheservicelog.Foreachservice,youcandecide: Whethertheserviceshouldgenerateauditdataduringexecution. Thepointsduringserviceexecutionwhentheserviceshouldgenerateauditdatato besavedintheservicelog. Whethertoincludeacopyoftheserviceinputpipelineintheservicelog. Audit properties for a service
Specifies if a service generates audit data. Specifies when to include the pipeline in the service log.

Specifies when a service generates audit data during execution.

Keepinmindthatgeneratingauditdatacanimpactperformance.TheIntegrationServer usesthenetworktosendtheauditdatatotheservicelogandusesmemorytoactually savethedataintheservicelog.Ifalargeamountofdataissaved,performancecanbe impacted.Whenyouconfigureauditdatagenerationforservices,youshouldbalancethe needforauditdataagainstthepotentialperformanceimpact. Thefollowingsectionsdescribetheoptionsforgeneratingauditdataandthepotential performanceimpactofeachoption.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

157

6 Building Flow Services

Note: Theservicelogcanbestoredinaflatfileoradatabase.Ifyouuseadatabase,the databasemustsupportJDBC.YoucanusetheIntegrationServertoviewtheservice logwhetheritisinaflatfileoradatabase.Iftheservicelogisinadatabase,youcan alsousethewebMethodsMonitortoviewauditdataandreinvoketheservice.Before youconfigureserviceauditing,checkwithyourIntegrationServerAdministratorto learnwhatkindofservicelogexists.Formoreinformationabouttheservicelog,see thewebMethodsAuditLoggingGuide.

Enabling Auditing for a Service


Whenyouconfigureserviceauditing,youfirstmustdecidewhetheryouwanttobeable toaudittheservice.Thatis,doyouwanttheservicetogenerateauditdatatobecaptured intheservicelog?Ifso,youmustdecidewhethertheservicewillgenerateauditdata everytimeitexecutesoronlywhenitisinvokeddirectlybyaclientrequest(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

Specifying When Audit Data Is Generated


Whenyouconfigureserviceauditing,youcanspecifythepointswhentheservice generatesauditdata.Youmightwantaservicetoproduceauditdatawhenitstarts, whenitendssuccessfully,whenitfails,oracombinationofthese.Usetheoptionsinthe Log onpropertyonthePropertiespaneltospecifywhenaservicegeneratesauditdata. Tip! Whenaservicegeneratesauditdata,italsoproducesanauditevent.Ifyouwant theauditeventtocauseanotheractiontobeperformed,suchassendinganemail notification,writeaneventhandler.Thensubscribetheeventhandlertoauditevents. Formoreinformationabouteventsandeventhandlers,seeChapter 15,Subscribing toEvents.

158

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

ThefollowingtabledescribeseachoptionintheLog onproperty.Keepinmindthatevery timetheservicegeneratesauditdata,theIntegrationServermustcapturethedataand writeittotheservicelog.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.Theservice logwillcontainanentryforeverytimetheservicefinishesprocessing. Performance Impact:Thisoptionimpactsperformanceeverytimethe serviceexecutes,whetheritendsbecauseoferrororsuccess.Ifyou areconcernedonlywithservicesthatfail,considerusingtheError only optioninstead. Error, success, and start Theservicegeneratesauditdatawhenitbeginsexecutingandwhenit finishesexecuting.Whentheserviceexecutestocompletion,the servicelogwillcontainastartentryandanendorerrorentry. Generally,mostservicesexecutefairlyquickly.Bythetimean administratorviewstheservicelogusingwebMethodsMonitor,the servicelogwouldprobablycontainentriesforthestartandendof serviceexecution.Situationswhereyoumightwanttheserviceto generateauditdataatthestartandendofserviceexecutioninclude: Tocheckforthestartoflongrunningservices Todetectservicehangs. Inbothsituations,ifserviceexecutionbeganbutdidnotcomplete,the servicelogcontainsanentryforthestartoftheservice,butnoentry fortheendoftheservice. Performance Impact:OfalltheoptionsunderLog on,thisoption providesthemostverboseandexpensivetypeofauditlogging.Every timeitexecutes,theservicegeneratesauditdataattwopoints:the beginningandtheend.TheIntegrationServermustwritetheaudit datatotheservicelogtwiceperserviceexecution.Thisrequires significantlymorediskutilizationthantheError onlyandError and successoptions.Atmost,theError onlyandError and successoptions requiretheIntegrationServertowriteauditdataonceperservice execution.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

159

6 Building Flow Services

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

Including the Pipeline in the Service Log


Whenyouconfigureserviceauditing,youcanspecifywhethertheservershouldinclude acopyoftheservicesinputpipelineintheservicelog.Iftheservicelogcontainsacopy oftheinputpipeline,youcanusethewebMethodsMonitortoperformmoreextensive failureanalysis,examinetheservicesinputdata,orreinvoketheservice.Usetheoptions intheInclude pipeline propertyonthePropertiespaneltospecifywhentheIntegration Servershouldsaveacopyoftheinputpipelineintheservicelog. Thepipelinedatasavedintheservicelogisthestateofthepipelinejustbeforethe invocationoftheservice.Itisnotthestateofthepipelineatthepointtheservice generatesauditdata.

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


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

TheservicelogwillcontaintheinputpipelineforServiceAonlyifitisthetoplevelservice (invokeddirectlybyaclientoratrigger)andtheserviceendsbecauseoffailure.If ServiceAisnotthetoplevelserviceorifServiceAexecutessuccessfully,theservicelogwill notcontainacopyoftheinputpipeline. Note: Includingthepipelineintheservicelogismorebeneficialwhentheservicelog isstoredinadatabase.TheIntegrationServercansavethepipelinetoaflatfile servicelog;however,youwillnotbeabletousethepipelinedatatoreinvokethe serviceorperformfailureanalysis.

160

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

ThefollowingtabledescribestheoptionsintheInclude pipeline propertyontheProperties panel.Keepinmindthatsavingtheinputpipelinetotheservicelogcanimpactthe performanceoftheIntegrationServer. Include pipeline Never Description TheIntegrationServerwillneversaveacopyoftheservicesinput pipelinetotheservicelog.Selectthisoptionifyouareusingaflatfile fortheservicelogorifyoudonotwanttobeabletoresubmitthe servicetotheIntegrationServer. Performance Impact:Thisoptionrequiresminimalnetworkbandwidth becausetheIntegrationServerneedstosendonlytheauditdata generatedbytheservicetotheservicelog. On errors only TheIntegrationServersavesacopyoftheinputpipelinetotheservice logonlywhentheservicegeneratesauditdatabecauseoffailure. Selectthisoptionifyouwanttousetheresubmissioncapabilitiesof thewebMethodsMonitortoreinvokeafailedservice.Formore informationaboutwebMethodsMonitor,seethewebMethods Monitordocumentation. Performance Impact:Forsuccessfulserviceinvocations,theOn errors only optionrequiresminimalnetworkbandwidth.Serviceinvocationsthat endinfailurerequiremorenetworkbandwidthbecausethe IntegrationServermustsavetheauditdataandtheinputpipeline. Theactualnetworkbandwidthneededdependsonthesizeofthe initialinputpipeline.Alargepipelinecandegradeperformance becauseitmaynegativelyimpacttherateatwhichthedataissavedto theservicelog.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

161

6 Building Flow Services

Include pipeline Always

Description TheIntegrationServersavesacopyoftheinputpipelinetotheservice logeverytimetheservicegeneratesauditdata.Iftheservice generatesdataatthestartandendofexecution(Log onissettoError, success, and start),theinputpipelineissavedwiththeservicelogentry 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 oftheinputpipelinetotheservicelogeverytimeaserviceexecutes. Theactualnetworkbandwidthneededdependsonthesizeofthe initialinputpipeline.Alargeinputpipelinecannegativelyimpactthe rateatwhichthedataissavedtotheservicelog.

Note: Ifyouwantauditeventsgeneratedbyaservicetopassacopyoftheinput pipelinetoanysubscribedeventhandlers,selectOn errors onlyorAlways.

Service Auditing Use Cases


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

Error Auditing
Inerrorauditing,youusetheservicelogtotrackandreinvokefailedservices.Tousethe servicelogforerrorauditing,servicesmustgenerateauditdatawhenerrorsoccur,and theIntegrationServermustsaveacopyoftheservicesinputpipelineintheservicelog. WithwebMethodsMonitor,youcanonlyreinvoketoplevelservices(thoseservices invokeddirectlybyaclientorbyaBroker/localtrigger).Therefore,ifyourintentwith errorauditingistoreinvokefailedservices,theserviceneedstogenerateauditdataonly whenitisthetoplevelserviceanditfails.

162

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

Tomakesuretheservicelogcontainstheinformationneededtoperformerrorauditing, 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

Tousetheservicelogforerrorauditing,storetheserviceloginadatabase.

Service Auditing
Whenyouperformserviceauditing,youusetheservicelogtotrackwhichservices executesuccessfullyandwhichservicesfail.Youcanperformserviceauditingtoanalyze theserviceloganddeterminehowoftenaserviceexecutes,howmanytimesitsucceeds, andhowmanytimesitfails.Tousetheservicelogforserviceauditing,servicesneedto generateauditdataafterexecutionends. Tomakesuretheservicelogcontainstheinformationneededtoperformservice auditing,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

Tousetheservicelogforserviceauditing,youcanstoretheservicelogineitheraflatfile oradatabase.

Auditing for Recovery


Auditingforrecoveryinvolvesusingtheservicelogtotrackexecutedservicesand serviceinputdatasothatyoucanreinvoketheservices.Youmightwanttoauditfor recoveryintheeventthataresourceexperiencesafatalfailure,andyouwanttorestore theresourcetoitsprefailurestatebyresubmittingserviceinvocations.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

163

6 Building Flow Services

Whenauditingforrecovery,youwanttobeabletoresubmitfailedandsuccessful services.Theservicelogneedstocontainanentryforeachserviceinvokedbyaclient requestoratrigger.Theservicelogalsoneedstocontainacopyofeachservicesinput pipeline. Tousetheservicelogtoauditforrecovery,selectthefollowingAuditproperties. For this property... Enable auditing Include pipeline Log on Select this option... When top-level service only Always Error and success

Tousetheservicelogtoauditforrecovery,storetheserviceloginadatabase.

Auditing Long-Running Services


Ifaservicetakesalongtimetoprocess,youmightwanttousetheservicelogtoverify thatserviceexecutionstarted.Iftheservicelogcontainsastartentryfortheservicebut noendorerrorentry,thenyouknowthatserviceexecutionbeganbutdidnotcomplete. Toenableauditingoflongrunningservices,selecttheError, success, and startoptionfor theLog onproperty. Note: Typically,youwillauditlongrunningservicesinconjunctionwitherror auditing,serviceauditing,orauditingforrecovery.

Setting Auditing Options for a Service


Thefollowingprocedureexplainshowtosetauditingoptionsforaservice.Theoptions youselectdetermineifandwhenaservicegeneratesauditdata,andwhethertheservice logincludesacopyoftheservicesinputpipeline.Makesurethatyouselectoptionsthat willprovidetheservicelogwiththeauditdatayourequire. Important! Beforeyouselectoptionsforgeneratingauditdata,checkwithyour IntegrationServerAdministratortodeterminewhatkindofservicelogexists.A servicelogcanbestoredinaflatfileoradatabase. To set auditing options for a service 1 Opentheserviceforwhichyouwanttoconfigureserviceauditing.Toconfigure serviceauditing,youmusthavewriteaccesstotheserviceandownthelockonthe service. Intheeditor,clicktheservicestitlebartogivetheservicethefocus.

164

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

6 Building Flow Services

IntheAuditcategoryofthePropertiespanel,selectanEnable auditingoptiontoindicate whenyouwanttheservicetogenerateauditdata. FormoreinformationabouttheEnable auditingoptions,seeEnablingAuditingfora Serviceonpage 158.

ForInclude pipeline,selectanoptiontoindicatewhentheIntegrationServershould includeacopyoftheinputpipelineintheservicelog. Note: Ifyouwantauditeventsgeneratedbythisservicetopassacopyoftheinput pipelinetoanysubscribedeventhandlers,selectOn errors onlyorAlways. FormoreinformationabouttheInclude pipelineoptions,includinginformationabout theperformanceimpact,seeIncludingthePipelineintheServiceLogonpage 160.

ForLog on,selectanoptiontodeterminewhentheservicegeneratesauditdata. FormoreinformationabouttheLog onoptions,includinginformationaboutthe performanceimpact,seeSpecifyingWhenAuditDataIsGeneratedonpage 158.

OntheFilemenu,clickSave. Important! TheoptionsyouselectintheAuditcategoryofthePropertiespanelcanbe overwrittenatruntimebythevalueofthewatt.server.auditLogserverproperty.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

165

6 Building Flow Services

Printing a Flow Service


ThefollowingproceduredescribeshowtousetheView as HTMLcommandtoproducea printableversionofaflowservice.Thisletsyouseeallaspectsofaflow(itsinputand outputparameters,itsflowsteps,andpipelinebehavior)inasingledocument. 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.

166

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Inserting Flow Steps


168 169 173 176 186 192 194 198 200

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

167

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

168

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

Inserting and Moving Flow Steps


Toinsertflowstepsinaflowservice,youmustopentheserviceintheeditor.Theflow stepsintheservicearelistedintheeditor.(Ifyoujustcreatedtheserviceanditdoesnot yetcontainanydefaultlogic,theeditorisempty). 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 Click this button... For more information, see page... 173 200 176

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

169

7 Inserting Flow Steps

To insert a/an... LOOPstep REPEATstep SEQUENCEstep EXITstep

Click this button...

For more information, see page... 194 186 192 198

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

170

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

Changing the Level of a Flow Step


Someflowstepshavesubordinatestepsonwhichtheyoperate.Subordinatestepsare referredtoaschildren.Forexample,whenyouusetheLOOPstep,thesetofstepsthat makeupthelooparereferredtoaschildrenofthatLOOPstep. Childrenarespecifiedbyindentingthembeneaththeirparentflowstep.Inthefollowing example,thetopBRANCHstephaschildrenandoneofitschildrenisaBRANCHstep, whichhasitsownsetofchildren. 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...

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

171

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 176andTheEXITSteponpage 198 foradditionalinformationaboutthisuseofthelabelproperty. Foracompletedescriptionofthepropertiesassociatedwitheachflowstep,see Appendix A,webMethodsFlowSteps.

172

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

173

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

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.

174

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 278. Validate output Whetherornotyouwanttheservertovalidatetheoutputofthe serviceagainsttheserviceoutputsignature.SelectTruetovalidate theoutput.SelectFalseifyoudonotwanttovalidatetheoutput. Forinformationaboutvalidatingoutput,seePerforming Input/OutputValidationonpage 278.

Timeout

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

175

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 177. IntheLabelpropertyofeachtargetstep,specifythevaluethatwillcausethatstepto execute.Formoreinformationaboutthisproperty,seeSpecifyingtheLabelValue onpage 177.

176

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 as the switch.

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.To doso,usethefollowingsyntaxtospecifythevalueinLabel: /RegularExpression/ Forexample,ifyouwanttoselectastepbasedonwhetheraPOnumberstartswiththe stringRELyouuse/^REL/asthevalueofLabel.Formoreinformationaboutregular expressions,seeAppendix B,RegularExpressions. Unlikeotherflowstepswhosechildrenexecuteinsequenceatruntime,onlyonechildof aBRANCHstepisexecuted:thetargetwhoselabelmatchesthevalueoftheswitch variable.Ifnoneofthetargetsmatchtheswitchvariable,noneofthemareperformed, andexecutionfallsthroughtothenextstepintheflowservice.Forexample,inthe followingflowservice,executionpassesdirectlytotheLogTransactionserviceifthevalue ofPaymentTypeisCOD.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

177

7 Inserting Flow Steps

An unmatched value will fall through the BRANCH

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

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

178

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 181. Important! TheexpressionsyoucreateforthechildrenofaBRANCHstepneedtobe mutuallyexclusive(onlyoneconditionshouldevaluatetotrueatruntime).

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

179

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.

180

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

181

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.

182

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

183

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... Specify... Comments Scope Anoptionaldescriptivecommentforthisstep. Thenameofadocument(IDataobject)inthepipelinetowhich youwanttorestrictthisstep.Ifyouwantthissteptohaveaccess totheentirepipeline,leavethispropertyblank. Themaximumnumberofsecondsthatthisstepshouldrun.Ifthis timeelapsesbeforethestepcompletes,theserverwaitsforthe steptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthisproperty, typethevariablenamebetween%symbols(forexample, %expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank. Label Anoptionalnameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank).Formoreinformationabout branchingonnulloremptyvalues,seeBranchingonNulland EmptyValuesonpage 180. Note: IfyouusethisstepasatargetforanotherBRANCHoran EXITstep,youmustspecifyavalueintheLabelproperty.Formore informationabouttheEXITstep,seeTheEXITStepon page 198. Switch ThenameoftheStringorconstrainedObjectvariablewhosevalue willbeusedtodeterminewhichchildsteptoexecuteatruntime. DonotspecifyaswitchvariableifyousettheEvaluate labels propertytoTrue. Whetherornotyouwanttoevaluatelabelsofchildstepsas conditionalexpressions.SelectTruetobranchonexpressions. SelectFalse(thedefault)ifyouwanttobranchontheswitchvalue.

Timeout

Evaluate labels

184

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

185

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.

186

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

187

7 Inserting Flow Steps

Using REPEAT to Retry a Failed Step


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

ExpirationofachildstepsTimeoutlimit AnexceptionthrownbyaJavaservice Adocumentquerythatreturnsanunpermittednullvalue

IfyouspecifymultiplechildrenunderaREPEATstep,thefailureofanyoneofthe childrenwillcausetheentiresetofchildrentobereexecuted. TheREPEATstepimmediatelyexitsasetofchildrenatthepointoffailure(thatis,if thesecondchildinasetofthreefails,thethirdchildisnotexecuted). WhenRepeat onissettoFAILURE,thefailureofachildwithinaREPEATstepdoes notcausetheREPEATstepitselftofailunlesstheCountlimitisalsoreached. TheTimeoutpropertyfortheREPEATstepspecifiestheamountoftimeinwhichthe entireREPEATstep,includingallofitspossibleiterations,mustcomplete.Whenyou useREPEATtoretryonfailure,youmaywanttoleavetheTimeoutvalueat0(no limit)orsetittoaveryhighvalue.Youcanalsosetthepropertytothevalueofa pipelinevariablebytypingthenameofthevariablebetween%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)inthepipelinetowhich youwanttorestrictthisstep.Ifyouwantthissteptohaveaccess totheentirepipeline,leavethispropertyblank.

188

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

For this property... Timeout

Specify... Themaximumnumberofsecondsthatthisstepshouldrun.If thistimeelapsesbeforethestepcompletes,theserverwaitsfor thesteptocompleteandthenraisesanexception. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%expiration%). Ifyoudonotneedtospecifyatimeoutperiod,leaveTimeout blank.

Label

AnoptionalnameforthisspecificREPEATstep,oranull, unmatched,oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHorEXIT step,youmustspecifyavalueintheLabelproperty.Formore informationabouttheBRANCHandEXITsteps,seeThe BRANCHSteponpage 176orTheEXITSteponpage 198.

Count

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

Repeat interval

Thelengthoftime(inseconds)thatyouwanttheservertowait betweeniterationsofthechildren. Ifyouwanttousethevalueofapipelinevariableforthis property,typethevariablenamebetween%symbols(for example,%waittime%).

Repeat on 4

FAILURE

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

Setthepropertiesforthechildstepasneeded.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

189

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

190

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

For this property... Label

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

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

191

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

192

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

193

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.

194

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

Specifying the Input Array


TheLOOPsteprequiresyoutospecifyaninputarraythatcontainstheindividual elementsthatwillbeusedasinputtooneormorestepsintheLOOP.Atruntime,the LOOPstepexecutesonepassoftheloopforeachmemberinthespecifiedarray.For example,ifyouwanttoexecuteaLOOPforeachlineitemstoredinapurchaseorder, youwouldusethedocumentlistinwhichtheorderslineitemsarestoredastheLOOPs 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

195

7 Inserting Flow Steps

Collecting Output from a LOOP Step


IfyourLOOPstepproducesanoutputvariable,theservercancollectthatoutputintoan arrayinthepipeline. Todothis,youusetheOutput arrayparametertospecifythenameofthearrayvariable intowhichyouwanttheservertocollectoutputforeachiterationoftheloop.For example,ifyourloopchecksinventorystatusofeachlineiteminapurchaseorderand producesaStringcalledInventoryStatuseachtimeitexecutes,youwouldspecify InventoryStatusasthevalueofOutput array.Atruntime,theserverwillautomatically 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.

Timeout

196

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

For this property Label

Specify AnoptionalnameforthisspecificLOOPstep,oranull, unmatched,oremptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHor EXITstep,youmustspecifyavalueintheLabelproperty.For moreinformationabouttheBRANCHandEXITsteps,see TheBRANCHSteponpage 176orTheEXITStepon page 198.

Input array

ThenameofthearrayvariableonwhichtheLOOPwill operate.Thisvariablemustbeoneofthefollowingtypes: Stringlist,Stringtable,Documentlist,Objectlist. Thenameoftheelementthatyouwanttheservertocollect eachtimetheLOOPexecutes.Youdonotneedtospecifythis propertyiftheloopdoesnotproduceoutputvaluesorifyou arecollectingtheelementsofInput array.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

197

7 Inserting Flow Steps

The EXIT Step


TheEXITflowstepallowsyoutoexittheentireflowserviceorasingleflowstep.You specifywhetheryouwanttoexitfrom: Thenearestancestor(parent)LOOPorREPEATflowsteptotheEXITflowstep. TheparentflowstepoftheEXITflowstep. AspecifiedancestorflowsteptotheEXITflowstep. Theentireflowservice. WhenyouusetheEXITstep,youindicatewhetherexitingshouldreturnasuccessful conditionorafailurecondition.Iftheexitisconsideredafailure,anexceptionisthrown. Youcanspecifythetextoftheerrormessagethatisdisplayedbytypingitdirectlyorby assigningittoavariableinthepipeline. 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 2 WheninsertinganEXITstepintoanexistingflowservice,displaythatserviceinthe editorandselectthestepimmediatelyabovewhereyouwanttheEXITstepinserted. Click ontheeditortoolbar.

198

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

7 Inserting Flow Steps

CompletethefollowingfieldsonthePropertiespanel: For this property Specify Comments Label Anoptionaldescriptivecommentforthisstep. Anoptionalnameforthisspecificstep,oranull,unmatched,or emptystring($null,$default,blank). Important! IfyouusethisstepasatargetforaBRANCHstep,you mustspecifyavalueintheLabelproperty.Formoreinformation abouttheBRANCHstep,seeTheBRANCHSteponpage 176. Exit from Theflowstepfromwhichyouwanttoexit.Specifyoneofthe following: Specify $loop $parent $flow Label To exit from the... NearestancestorLOOPorREPEATflowstep. Parentflowstep,regardlessofthetypeofstep. Entireflow. Nearestancestorflowstepthathasalabelthat matchesthisvalue. Note: Ifthelabelyouspecifydoesnotmatchthelabel ofanancestorflowstep,theflowwillexitwithan exception. Signal Whethertheexitistobeconsideredasuccessorafailure.Specify oneofthefollowing: Specify SUCCESS FAILURE To Exittheflowserviceorflowstepwithasuccess condition. Exittheflowserviceorflowstepwithafailure condition.Anexceptionisthrownaftertheexit.You specifytheerrormessagewiththeFailure message property.

Failure message

Thetextoftheexceptionmessageyouwanttodisplay.Ifyouwant tousethevalueofapipelinevariableforthisproperty,typethe variablenamebetween%symbols(forexample,%mymessage%). ThispropertyisnotusedwhenSignalissettoSUCCESS.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

199

7 Inserting Flow Steps

The MAP Step


TheMAPstepletsyouadjustthecontentsofthepipelineatanypointinaflowservice. WhenyoubuildaMAPstep,youcan: Preparethepipelineforusebyasubsequentstepintheflowservicebylinking, adding,anddroppingvariablesinthepipeline. Cleanupthepipelineafteraprecedingstepbyremovingfieldsthatthestepadded butarenotneededbysubsequentsteps. Movevariablesorassignvaluestovariablesinthepipeline. Initializetheinputvaluesforaflowservice. Invokeseveralservices(transformers)inasinglestep. Mapdocumentsformoneformattoanother.Forexample,youcanmapadocument inanXMLformattoanebXMLformatoraproprietaryformat. Tip! TheMAPstepisespeciallyusefulforhardcodinganinitialsetofinputvaluesin aflowservice.Touseitinthisway,inserttheMAPstepatthebeginningofyourflow, andthenusetheSet Valuemodifiertoassignvaluestotheappropriatevariablesin Pipeline Out. FormoreinformationabouttheMAPstep,seeChapter 8,MappingDatainaFlow Service.

200

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Mapping Data in a Flow Service


202 202 207 227

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

201

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.

202

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

203

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.Forinformationabout applyingconstraintstovariables,seeApplyingConstraintstoVariableson page 273.

204

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 229. ThePipeline Out columnrepresentstheoutputoftheMAPstep.Itcontainsthenames ofvariablesthatwillbeavailableinthepipelinewhentheMAPstepcompletes. WhenyoufirstinsertaMAPstepintoyourflow,Pipeline InandPipeline Outareidentical. However,iftheMAPstepistheonlystepintheflowserviceoristhelaststepintheflow service,Pipeline Outalsodisplaysthevariablesdeclaredasoutputintheflowservice. OnthePipelinetab,youcaninsertpipelinemodifierstoadjustthecontentsofthe pipeline.Forexample,youcanlinkvariablesfromPipeline IntoservicesinTransformers. Youcanalsousepipelinemodifierstoassignvaluestopipelinevariables,dropvariables fromthepipeline,oraddvariablestothepipeline.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

205

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 207. Drop a variable from the pipeline.TheDropmodifierremoves extraneousvariablesfromthepipeline.Forinformationabout usingthispipelinemodifier,seeDroppingVariablesfromthe Pipelineonpage 225. Assign a value to a variable.TheSet Valuemodifierhardcodesa valueforavariable.Forinformationaboutthispipelinemodifier, seeAssigningValuestoPipelineVariablesonpage 221.

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 5 6 OpentheflowserviceforwhichyouwanttoprintthePipelinetab. Intheeditor,selecttheINVOKEorMAPstepforwhichyouwanttoprintthePipeline tab. ClickanywhereonthePipelinetab. ScrollorresizethePipelinetabtodisplaytheportionofthepipelineyouwanttoview asHTML. OntheFilemenu,clickView as HTML. DevelopercreatesanHTMLpageanddisplaysitinyourdefaultbrowser. Ifyouwanttoprintthepipeline,useyourbrowsersprintcommand.

206

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Basic Mapping Tasks


Basicmappingtasksarethetasksyouperformtomanagethepipelinecontentsandthe valuesofvariablesinthepipeline.OnthePipelinetab,youcanperformthefollowing basicmappingtasks: Link variables to each other.Youcancopythevalueofavariableinoneserviceor documentformattoavariableinanotherserviceordocumentformat. Assign values to variables.Youcanhardcodevariablevaluesorassignadefaultvalue tovariables. 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... 207 214 216 219 219 221 225 226 62

Linking Variables
Whenyouwanttocopythevalueofavariableinaserviceordocumentformatto anothervariable,youlinkthevariables.Developerconnectsserviceandpipeline variablesonthePipelinetabwithalinecalledalink.Creatingalinkbetweenvariables copiesthevaluefromonevariabletoanotheratruntime. Withinaflow,Developerimplicitlylinksvariableswhosenamesarethesameandwhose datatypesarecompatible.Forexample,theserviceinthefollowingflowtakesavariable calledAcctNumber.BecauseavariablebythisnamealreadyexistsinPipeline In,itis automaticallylinkedtotheAcctNumbervariableinService In.Developerconnects implicitlylinkedvariableswithagraylink.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

207

8 Mapping Data in a Flow Service

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

208

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Important! DonotlinkvariableswithdifferentObjectconstraints.Ifyoulinkvariables withdifferentobjectconstraintsandinput/outputvalidationisselected,theruntime resultisundefined. Alltheoutputvariablesthataserviceproducesareautomaticallyplacedinthepipeline. JustasyoucanlinkvariablesfromthePipeline Instagetoaservicesinputvariables,you canlinktheoutputfromaservicetoadifferentvariableinPipeline Out. Inthefollowingexample,avariablecalledTransNumberislinkedtothefieldNumina documentcalledTransactionRecord.Atruntime,theserverwillcopythevalueof TransNumbertoNum,andbothTransNumberandNumwillbeavailabletosubsequent servicesintheflow. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

209

8 Mapping Data in a Flow Service

Bylinkingvariablestoeachother,youarecopyingdatafromthesourcevariabletothe targetvariable.(Documents,however,arecopiedbyreference.Formoreinformation, seeWhatHappensWhenIntegrationServerExecutesaLinkBetweenVariables?on page 211.) Targetvariablescanbeconnectedtoonlyonesourcevariable.Afteryoudrawalink toatargetvariable,youcannotdrawanotherlinktothetargetvariable.(Two exceptionstothisruleinvolvearrayvariablesandconditionallinks.Formore informationaboutlinkingarrayvariables,seeLinkingtoandfromArrayVariables onpage 216.Formoreinformationaboutplacingconditionsonlinksbetween variables,seeApplyingConditionstoLinksBetweenVariablesonpage 219. YoucannotcreatealinktoavariableifyoualreadyusedtheSet Valuemodifierto assignavaluetoavariable. AfteraLinkmodifierisexecuted,boththesourceandtargetvariablesexistinthe pipeline.Thetargetvariabledoesnotreplacethesourcevariable. To create a link between variables 1 2 3 Intheeditor,selecttheINVOKEorMAPstepcontainingthevariablesyouwantto link. ClickthePipelinetab. IfyouwanttocreatealinkbetweenavariableinPipeline InandoneinService In,do thefollowing: 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 216.

210

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Ifyouwanttoplaceaconditionontheexecutionofthelink,seeApplying ConditionstoLinksBetweenVariablesonpage 219. DonotlinkvariableswithdifferentObjectconstraints.Ifyoulinkvariableswith differentobjectconstraintsandinput/outputvalidationisselected,theruntime resultisundefined.

Tip! Youcanalsouseyourmousetolinkvariablestooneanother.Todothis,selectthe sourcevariableanddragyourmousetotheappropriatetargetvariable. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

211

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.

212

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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. Topreventthevalueofthetargetvariablefrombeingoverwrittenbychangestothe valueofthesourcevalueinsubsequentstepsintheflowservice,youcandooneofthe following: Whenworkingwithdocumentvariables,linkeachchildofthedocumentvariable individually.Thismethodcanbetimeconsumingandmightsignificantlyincrease thememoryandtimerequiredtoruntheservice.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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

213

8 Mapping Data in a Flow Service

AfterthechildvariableofadocumentordocumentlististhetargetofaLinkmodifier, theparentdocumentordocumentlistcannotbeatargetofaLinkmodifier. 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 431. Whenyoulinkbetweenscalarandarrayvariables,youcanspecifywhichelementof thearrayvariableyouwanttolinktoorfrom.Scalarvariablesarethosethatholda singlevalue,suchasString,document,andObject.Arrayvariablesarethosethathold multiplevalues,suchasStringlist,Stringtable,documentlist,andObjectlist.For example,youcanlinkaStringtothesecondelementofaStringlist.Alternatively, youcanlinkthesecondelementinaStringlisttoaString. Whenyoulinkbetweenscalarandarrayvariablesandyoudonotspecifywhich elementinthearrayvariablethatyouwanttolinktoorfrom,Developerusesthe defaultbehaviortodeterminethevalueofthetargetvariable. Formoreinformationaboutthedefaultbehaviorforlinkingarrayvariables,seeDefault PipelineRulesforLinkingtoandfromArrayVariablesonpage 433.

214

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

215

8 Mapping Data in a Flow Service

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

Linking to and from Array Variables


Whenyoulinktoorfromanarrayvariable(Stringlist,Stringtable,documentlist,or Objectlist),youcanspecifywhichelementinthearrayyouwanttolinktoorfrom.After youlinkthevariables,youspecifytheindexthatrepresentsthepositionoftheelementin thearray. ForStringlistsandObjectlists,youcanspecifytheindexforthelistelementyou wanttolink.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.

216

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

217

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 433. IfyouarelinkingtoorfromaStringtable,youneedtospecifyanindexvalueforthe rowandcolumn. Whenyoulinkadocumentordocumentlistvariabletoanotherdocumentor documentlistvariable,thestructureofthesourcevariabledeterminesthestructureof thetargetvariable.Formoreinformation,seeLinkingtoDocumentandDocument ListVariablesonpage 213. Thefollowingprocedureexplainshowtolinktoorfromanarrayvariable.

218

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

219

8 Mapping Data in a Flow Service

Pipeline IntotheOrderTotalvariableinService InonlyiftheBuyersTotalhasavaluethatis 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 176.

220

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

To apply a condition to the link between variables 1 2 3 4 CreatealinkbetweenthevariablesusingtheproceduredescribedinTocreatealink betweenvariablesonpage 210. 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 312.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

221

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.

222

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

223

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

224

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

225

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.

226

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

227

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.

228

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

229

8 Mapping Data in a Flow Service

To insert a transformer 1 2 3 Intheeditor,selecttheMAPstepinwhichyouwanttoinsertatransformer. ClicktheTransformersareaonthePipelinetab. Click onthePipelinetabtoolbarandthenselecttheserviceyouwanttoinvoke. Iftheserviceyouwanttoinsertdoesnotappearinthelist,selectBrowsetoselectthe servicefromtheNavigationpanel.ThetransformerappearsunderTransformers onthe Pipelinetab. 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 234. Validate output Whetherornotyouwanttovalidatetheoutputofthe transformeragainstthesignatureoftheservice.SelectTrueto validatetheoutputofthetransformer.SelectFalseifyoudo notwanttovalidatetheoutputofthetransformer. Forinformationaboutvalidatingtransformers,seeValidating InputandOutputforTransformersonpage 234. 5 ClickOK. Forinformationaboutdebuggingtransformers,seeDebuggingTransformerson page 237. Tip! WhenyouexpandatransformerintheTransformersareaofthePipelinetab,you canseetheService InvariablesandtheService Out variablesandalloftheexplicitlinks betweenthetransformerandthepipeline.Youmightfinditeasiertolinktransformer variableswhenyouarezoomedinonthetransformer.

Validate input

230

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Linking Variables to a Transformer


Whenyoumapdatatoandfromatransformer,youcreatelinksbetweenthepipeline variablesandthetransformer.Keepthefollowingpointsinmindwhenyoucreatelinks betweenpipelineandtransformervariables: Developerdoesnotimplicitlylinkpipelinevariablestotheinputoroutputvariables ofatransformer.Evenifthepipelinevariableshavethesamenameanddatatypeas thetransformervariables,noimplicitlinkingoccurs.Youneedtoexplicitlylink pipelinevariablestotheinputandoutputvariablesofatransformer. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

231

8 Mapping Data in a Flow Service

TocreatealinkbetweenatransformeroutputvariableandaPipeline Outvariable,do thefollowing: a b c SelectthetransformeranddragyourmousetothevariableinPipeline Outtowhich youwanttolinkthetransformervariable. IntheLink Fromlist,selectthetransformervariablethatyouwanttolinktothe selectedPipeline Outvariable. Repeatsteps aandbforeachoutputvariableproducedbythetransformer. YoucanlinkatransformeroutputvariabletomorethanonePipeline Outvariable. 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.

232

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

What Is Dimensionality? Dimensionalityreferstothenumberofarraystowhichavariablebelongs.Forexample, thedimensionalityofasingleStringis0,thatofasingleStringlistordocumentlistis1, andthatofasingleStringtableis2.AStringthatisachildofadocumentlisthasa dimensionalityof1.AStringlistthatisachildofadocumentlisthasadimensionality of 2. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

233

8 Mapping Data in a Flow Service

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

234

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Important! Copyingatransformerdoesnotcopythelinksbetweentransformer variablesandpipelinevariablesoranyvaluesyoumighthaveassignedto transformervariablesusingtheSet Valuemodifier. To copy a transformer 1 2 3 4 5 Intheeditor,selecttheMAPstepcontainingthetransformerserviceyouwantto copy. ClickthePipelinetab. UnderTransformers,selectthetransformerserviceyouwanttocopy.Rightclickthe transformerandthenselectCopy. Topastethetransformer,clickanywhereunderTransformers.Rightclickandselect Paste. Linktheinputandoutputvariablesofthetransformerusingtheprocedures describedinLinkingVariablestoaTransformeronpage 231.

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

Whenyouexpandatransformer,youcanonlyperformactionsforthattransformer,for example,youcanonlylinkvariablesorsetpropertiesfortheexpandedtransformer. Othertransformersandlinkstoothertransformersremainhiddenuntilyoucollapsethe transformer.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

235

8 Mapping Data in a Flow Service

Note: Ifyouexpandatransformer,youcanusetheSet Valuemodifiertoassignavalue toavariableinService In. To expand and collapse the contents of a transformer Toexpandthecontentsofatransformer,clickComposeExpand. Tocollapsethecontentsofatransformer,clickComposeCollapse. Tip! Youcanalsoexpand/collapseatransformerbydoubleclickingit. 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 47. To rename a transformer 1 2 3 4 UsetheNavigationpaneltodeterminethenewnameorlocationoftheservicecalled bythetransformer. Opentheflowservicecontainingthetransformeryouwanttorename. Intheeditor,selecttheMAPstepcontainingthetransformer.Then,onthePipelinetab, selectthetransformeryouwanttorename. IntheServicepropertyonthePropertiespanel,deletetheoldnameandtypeinthe servicesnewfullyqualifiednameinthefolderName:serviceNameformat,orclick to selectaservicefromalist.

236

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

8 Mapping Data in a Flow Service

Debugging Transformers
Whenyoutestanddebugaflowservice,youcanusethefollowingtestingand debuggingtechniqueswithtransformers: StepintoaMAPstepandstepthroughtheexecutionofeachtransformer.Formore informationaboutsteppingintoandoutofaMAPstep,seeUsingtheStepTools withaMAPSteponpage 306. Setabreakpointonatransformersothatserviceexecutionstopswhenthe transformerisencountered.Formoreinformationaboutsettingbreakpoints,see SettingBreakpointsonpage 307. Disableatransformersothatitdoesnotexecuteatruntime.Formoreinformation aboutdisablingtransformers,seeDisablingTransformersonpage 311. Note: YoucanalsousethePipelinedebugpropertywhentestinganddebuggingthe flowservicetoviewtheactivityofatransformer.ThePipelinedebugproperty enablesyoutoeasilytestanotherserviceagainstthecurrentsetofpipelinevaluesor ifyouwanttorestorethepipelinetothisexactstatelaterinthedebuggingprocess.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

237

8 Mapping Data in a Flow Service

238

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Creating IS Schemas, IS Document Types, and Specifications


240 250 267

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

239

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

What Does an IS Schema Look Like?


TheappearanceandcontentofanISschemadependsonwhetheryougenerateanIS schemafromanXMLschemaoraDTD.Forexample,ifyoucreateanISschemafroman XMLschema,theresultingISschemadisplaystypedefinitions,elementdeclarations,and attributedeclarations.IfyoucreateanISschemafromaDTD,theresultingISschema displayselementtypedeclarations. WhenyouselectanISschemaintheNavigationpanel,Developerdisplaysthecontents oftheISschemaintheeditor.Theschemaeditorisdividedintotwoareas:theschema browserontheleftandtheschemadetailsareaontheright.Abovetheseareas,theeditor identifiesthetargetnamespacefortheISschema.

240

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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,ifyoucreateanISschemafromanXMLschemathatdoes notcontainanyglobalattributedeclarations,theschemabrowserdoesnotdisplaythe ATTRIBUTESheading.AnISschemacreatedfromaDTDneverdisplaystheSIMPLE TYPESorCOMPLEXTYPESheadingsbecauseDTDsdonotcontaintypedefinitions. Note: ADTDdoescontainattributedeclarations.However,theschemabrowserdoes notdisplaytheATTRIBUTESheadingforISschemasgeneratedfromDTDs.Thisis becauseanattributedeclarationinaDTDassociatestheattributewithanelement type.Accordingly,theschemabrowserdisplaysattributesaschildrenoftheelement typedeclarationtowhichtheyareassigned.Formoreinformation,seethe webMethodsIntegrationServerSchemaReference. TheschemabrowserusesuniquesymbolstorepresentthecomponentsoftheISschema. EachofthesesymbolsrelatestoacomponentofanXMLschemaoraDTD.Thefollowing tableidentifiesthesymbolforeachcomponentthatcanappearinanISschema.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

241

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.

242

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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"attributeinanXMLschemacomplextypedefinitionoraDTD elementlistinwhichthefirstitemis#PCDATA. Empty content.InanXMLschema,anelementhasemptycontentwhenits associatedcomplextypedefinitiondoesnotcontainanyelement declarations.Anelementwithemptycontentmaystillcarryattributes. InaDTD,anelementhasemptycontentwhenitisdeclaredtobeoftype EMPTY.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

243

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,theschemadetailsarealookslikethe following: Schema details area for a simple type definition

If you select a simple type definition...

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

244

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

About Schema Domains


EachISschemaonIntegrationServerbelongstoaschemadomain.Aschemadomainisa namedcollectionofISschemas. Withineachschemadomain,theschemacomponentssuchaselementdeclarations, attributedeclarations,typedefinitionsforanXMLnamespacesmustbeunique. However,morethanoneschemadomaincancontainthesameschemacomponentsfor anXMLnamespace.ThisallowsIntegrationServertomaintainmultipleISschemasfor thesameXMLnamespace. IfyouwanttomaintainalternatedefinitionsofschemacomponentsforanXML namespaces,assigntheISschemasthatcontainthosecomponentstodifferentschema domains. IntegrationServercontainsadefaultschemadomaininwhichanyISschemascreated priortoversion8.0reside.Youcanplacenewschemasinthedefaultschemadomainor youcanspecifyadifferentschemadomain.Aschemadomainnameisanystringthatisa validnameofanelementinIntegrationServer.Formoreinformationaboutnaming restrictionsforIntegrationServerelements,seeGuidelinesforNamingElementson page 46. WhenIntegrationServerconsumesaWSDLdocumenttocreateawebservicedescriptor, IntegrationServerplacesanygeneratedISschemasinthedefaultschemadomain.

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 OntheFilemenu,clickNew. IntheNewdialogbox,selectSchema,andthenclickNext. IntheNewSchemadialogbox,nexttoFolder,selectthefolderwhereyouwantto savetheISschema.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

245

9 Creating IS Schemas, IS Document Types, and Specifications

IntheNamefield,typeanamefortheISschemausinganycombinationofletters, numbers,andtheunderscorecharacter.ClickNext. Important! Ifyouspecifyanamethatusesareservedwordorcharacter, webMethodsIntegrationServerdisplaysanerrormessage.Whenthishappens, useadifferentnameortryaddingaletterornumbertothenametomakeitvalid. Formoreinformationaboutrestrictedcharactersforpackages,folders,and elements,seeAboutElementNamesonpage 45.

IntheNewSchemadialogbox,selectoneofthefollowingtospecifythesourceforthe ISschema. Specify... XML DTD XML Schema To... CreateanISschemabasedonanexistingDTDreferencedbyanXML document. CreateanISschemabasedonaDTD. CreateanISschemabasedonanXMLschemadefinition.

Important! YoucancreateanISschemafromanXMLdocumentonlyiftheXML documentreferencesanexistingDTD. 6 7 ClickNext. IntheEnter the URL or select a local filebox,dooneofthefollowing:

IfyouwanttobasetheISschemaonanXMLdocument,DTD,orXMLschema definitionthatresidesontheInternet,typetheURLoftheresource.(TheURL youspecifymustbeginwithhttp:orhttps:.) IfyouwanttobasetheISschemaonanXMLdocument,DTD,orXMLschema definitionthatresidesonyourlocalfilesystem,typethepathandfilename,or click tonavigatetoandselectthefile.

UnderSchema domain,specifytheschemadomaintowhichthegeneratedISschema willbelong.Dooneofthefollowing:

ToaddtheISschematothedefaultschemadomain,selectUse default schema domain. ToaddtheISschemastoaspecifiedschemadomain,selectUse specified schema domainandprovidethenameoftheschemadomaininthetextbox.Aschema domainnamemustbeastringthatisavalidnameofanelementinIntegration Server.FormoreinformationaboutnamingrestrictionsforIntegrationServer elements,seeGuidelinesforNamingElementsonpage 46. Formoreinformationaboutschemadomains,seeAboutSchemaDomainson page 245.

246

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

ClickFinish.DevelopergeneratestheISschemausingthedocumentyouspecified anddisplaysitintheeditor. Note: YoumightreceiveerrorsorwarningswhencreatinganISschemafromanXML schemadefinitionorDTD.Formoreinformationabouttheseerrorsandwarnings, seeAppendix G,ValidationErrorsandExceptions. Note: WhencreatinganISschemafromanXMLschemadefinition,Developer validatestheschemaanddoesnotcreatetheISschemaiftheXMLschemadefinition isnotvalid.Formoreinformation,seeISSchemaGenerationErrorsandWarnings onpage 497.

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.Thefollowing mechanismscanbeusedtoreferenceanexternalschema: 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 schemanamedmySchemafrommySchema.xsd,theschemaprocessorgeneratesan ISschemanamedmySchema_2fortheimportedXMLschema. Redefine.Schemaauthorscanalsouse<redefine>toincludeandthenredefinetype definitions,modelgroups,andattributegroupsfromanexternalXMLschemainthe samenamespace.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

247

9 Creating IS Schemas, IS Document Types, and Specifications

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.

Whenmodifyingasimpletypedefinition,keepthefollowingpointsinmind: Changestoasimpletypedefinitionaffecttheelementsandattributesforwhichthe simpletypeisthedefinedtype.Forexample,iftheattributepartNumisdefinedtobe oftypeSKU,changestotheSKUsimpletypedefinitionaffectthepartNumattribute. ChangestoaglobalsimpletypedefinitioninanISschemadonotaffectsimpletypes derivedfromtheglobalsimpletype;thatis,thechangesarenotpropagatedtothe derivedtypesintheISschema.

248

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

SimpletypesinanISschemacanbeusedascontentconstraintsforfieldsinpipeline validation.Consequently,changestoasimpletypealsoaffecteveryfieldtowhichthe simpletypeisappliedasacontentconstraint. Tip! Youcancreateacustomsimpletypetoapplytoafieldasacontenttype constraint.Formoreinformationaboutcreatingacustomsimpletypeand applyingconstraintstofields,seeSettingConstrainingFacetValueson page 249. ChangestoasimpletypedefinitionaresavedintheISschema.Ifyouregeneratethe ISschemafromtheXMLschemadefinition,yourchangeswillbeoverwritten. Whenyouedittheconstrainingfacetsappliedtoasimpletypedefinition,youcan onlymaketheconstrainingfacetvaluesmorerestrictive.Theconstrainingfacets cannotbecomelessrestrictive.Formoreinformationaboutsettingvaluesfor constrainingfacets,seeSettingConstrainingFacetValuesonpage 249. 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 473. OntheFilemenu,clickSave.

Setting Constraining Facet Values


Youcaneditanyoftheconstrainingfacetvaluesthatappearintheschemadetailsarea whenyouselectaneditablesimpletypedefinitionintheschemabrowser.The constrainingfacetsdisplayedintheschemadetailsareadependontheprimitivetype fromwhichthesimpletypewasderived.Forexample,ifthesimpletypedefinitionis derivedfromstring,theschemadetailsareadisplaystheenumeration,length,minLength, maxLength,pattern,andwhiteSpacefacets.Theschemadetailsareaonlydisplays constrainingfacetvaluessetinthesimpletypedefinition.Itdoesnotdisplay constrainingfacetvaluesthesimpletypedefinitioninheritedfromthesimpletypesfrom whichitwasderived.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

249

9 Creating IS Schemas, IS Document Types, and Specifications

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. YoucancreateanISdocumenttypeinthefollowingways: CreateanemptyISdocumenttypeanddefinethestructureofthedocumenttype yourselfbyinsertingfields. CreateanISdocumenttypefromasourcefile,suchasanXMLschema,DTD,orXML document.ThestructureandcontentoftheISdocumenttypewillmatchthatofthe sourcefile. CreateanISdocumenttypefromaBrokerdocumenttype.

250

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

Creating an Empty IS Document Type


WhenyoucreateanemptyISdocumenttype,youinsertfieldstodefinethecontentsand structureoftheISdocumenttype. Note: IfyouintendtomaketheISdocumenttypepublishable,keepinmindthatthe Brokerhasrestrictionsforfieldnames.Ifyoucreateatriggerthatsubscribestothe publishabledocumenttype,anyfiltersthatincludefieldnamescontainingrestricted characterswillbesavedontheIntegrationServeronly.Thefilterswillnotbesaved ontheBroker,possiblyaffectingIntegrationServerperformance.Formore information,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 45. ClickNext.

c 4 5 6

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

TypethenameofthefieldandthenpressENTER. Note: Developerpreventstheinsertionoffieldsnamed_envinanISdocument type.Fordetailsaboutthe_envfield,seeTheEnvelopeFieldonpage 261.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

251

9 Creating IS Schemas, IS Document Types, and Specifications

Withthefieldselected,setfieldpropertiesandapplyconstraintsintheProperties panel(optional). Formoreinformationaboutsettingfieldproperties,seeSpecifyingField Propertiesonpage 265.Forinformationaboutapplyingconstraints,see ApplyingConstraintstoVariablesonpage 273.

Ifthefieldisadocumentoradocumentlist,repeatsteps actodefineandsetthe propertiesandconstraintsforeachofitsmembers.Use fieldbeneaththedocumentordocumentlistfield. toindenteachmember

OntheFilemenu,clickSave. Note: Developerdisplayssmallsymbolsnexttoafieldicontoindicatevalidation constraints.Developeruses toindicateanoptionalfield.Developerusesthe symboltodenoteafieldwithacontentconstraint.Forinformationaboutapplying constraintstofields,seeApplyingConstraintstoVariablesonpage 273.

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.

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" ?>

252

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

Points to Consider When Using an XML Schema As the Source


KeepthefollowingpointsinmindwhencreatinganISdocumenttypefromanXML schema: BeforecreatingtheISdocumenttypeandtheISschema,IntegrationServervalidates theXMLschema.IftheXMLschemadoesnotconformsyntacticallytotheschemafor XMLschemasdefinedinXMLSchemaPart1:Structures,IntegrationServerdoesnot createanISschemaoranISdocumenttype.Instead,Developerdisplaysanerror messagethatliststhenumber,title,location,anddescriptionofthevalidationerrors withintheXMLschema. YoucanspecifythenamespaceprefixesthatyouwanttouseintheISdocumenttype. TheprefixyouassignmustbeuniqueandmustbeavalidXMLNCNameasdefined bythespecificationhttp://www.w3.org/TR/RECxmlnames/#NTNCName. Bydefault,IntegrationServerusestheprefixesdeclaredintheXMLschemaaspartof thefieldnames.Fieldnameshavetheformatprefix:elementNameor prefix:@attributeName. IftheXMLschemadoesnotuseprefixes,theIntegrationServercreatesprefixesfor eachuniquenamespaceandusesthoseprefixesinthefieldnames.IntegrationServer usesnsastheprefixforthefirstnamespace,ns1forthesecondnamespace, ns2. YoucanselectoneormoreglobalelementdeclarationsastherootnodefortheIS documenttype.IntegrationServerincludesalloftheselectedelementsinthesameIS documenttype.TheselectedelementsappearastoplevelfieldsinthegeneratedIS documenttype. WhentheXMLschemacontainsonlyonereferencetoaparticularglobalelementof complextype,youcanspecifywhetherIntegrationServerrepresentstheelement referencewithoneofthefollowing:

Adocumentdefinedinline.IntegrationServerinsertsadocumentfieldforthe globalelementintheISdocumenttype.Thedocumentfieldcontentscorrespond tothecontentmodeloftheglobalelement.Thisisthedefault. Adocumentreference.IntegrationServerinsertsadocumentreferencetoanIS documenttypewhosecontentcorrespondstothecontentmodeloftheglobal element. Note: IntegrationServerusesdocumentreferencesautomaticallyiftheXML schemacontainsmultiplereferencestoaparticularglobalelement.

IntegrationServeralwaysexpandselementreferencestoelementdeclarationsof simpletypeinline.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

253

9 Creating IS Schemas, IS Document Types, and Specifications

IntegrationServercancreateseparateISdocumenttypesfornamedcomplextypesor expanddocumenttypesinlinewithinonedocumenttype.Formoreinformation,see ExpandingComplexDocumentTypesInlineonpage 254. IntegrationServergeneratesaseparateISdocumenttypeforanyreferencedcomplex typeandgeneratesanISdocumenttypeforanytypesderivedfromthereferenced complextypes. YoucanspecifywhetherornotIntegrationServergeneratesISdocumenttypesforall complextypesregardlessofwhetherthetypesarereferencedornot.When watt.core.schema.generateAllTypeDocumentsissettotrueIntegrationServer generatesanISdocumenttypeforeverycomplextypedefinitionintheXMLschema. Whenthispropertyissettofalse,IntegrationServergeneratesaseparateIS documenttypeforacomplextypeonlyifthecomplextypeisreferencedorisderived fromareferencedcomplextype. IntegrationServercancreateonefieldforasubstitutiongrouporcreatefieldsfor everymemberelementinasubstitutiongroup.Formoreinformation,see GeneratingFieldsforSubstitutionGroupsonpage 256. 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>

254

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

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

Ifyouselecttheoptiontogeneratecomplextypesasseparatedocumenttypes,the schemaprocessorgeneratesthedocumenttypesasfollows.Inthisexample,theschema processorgeneratedthreeISdocumenttypesoneforthecomplextypenamed documentY,oneforthecomplextypenameddocumentX(withareferencetodocumentY), andonefortherootelementeltA(withreferencestodocumentXanddocumentY): Complex types generated as separate document types

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

255

9 Creating IS Schemas, IS Document Types, and Specifications

Theschemaprocessorgeneratesallthreedocumenttypesinthesamefolder. Note: Ifthecomplextypeisanonymous,theschemaprocessorexpandsitinlinerather thangenerateaseparatedocumenttype. IftheXMLschemayouareusingtogenerateanISdocumenttypecontainsrecursive complextypes(thatis,elementdeclarationsthatrefertotheirparentcomplextypes directlyorindirectly),youcanavoiderrorsinthedocumenttypegenerationprocessby selectingtheoptiontogeneratecomplextypesasseparatedocumenttypes.(Selectingthe optiontoexpandcomplextypesinlinewillresultininfinitelyexpandingnested documents.) 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 45. ClickNext.

256

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

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

5 6

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

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

UnderSchema domain,specifytheschemadomaintowhichanyISschemasgenerated willbelong.Dooneofthefollowing:

ToaddtheISschematothedefaultschemadomain,selectUse default schema domain. ToaddtheISschemastoaspecifiedschemadomain,selectUse specified schema domainandprovidethenameoftheschemadomaininthetextbox.Aschema domainnamemustbeastringthatisavalidnameofanelementinIntegration Server.FormoreinformationaboutnamingrestrictionsforIntegrationServer elements,seeGuidelinesforNamingElementsonpage 46. Formoreinformationaboutschemadomains,seeAboutSchemaDomainson page 245.

Dooneofthefollowingbasedonyourselectioninstep4:

IfyouselectedXML,clickFinish.DevelopergeneratestheISdocumenttypeusing theXMLdocumentyouspecifiedanddisplaysitintheeditor. IfyouselectedDTD,clickNext.Developerpromptsyoutoselecttherootelement ofthedocument.SelecttherootelementandclickOK.DevelopergeneratestheIS documenttypeanddisplaysitintheeditor.DeveloperalsogeneratesanIS schemaanddisplaysitintheNavigationpanel.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

257

9 Creating IS Schemas, IS Document Types, and Specifications

IfyouselectedXML Schema,clickNext anddothefollowing: 1 SelecttheelementsthatyouwanttouseastherootelementsfortheIS documenttype.TheISdocumenttypewillcontainalloftheselectedroot elements. Toselectmultipleelements,presstheCTRLkeywhileselectingelements. 2 UnderComplex type processing,selectExpand complex types inlineifyouwant complextypestobeexpandedwithintheISdocumenttype.Thatis,the complextypewillbeadocumentvariablewithintheISdocumenttype. SelectGenerate complex types as document typesifyouwantseparateIS documenttypescreatedforthecomplextypesintheXMLschemadefinition. TheresultingISdocumenttypecontainsdocumentreferencesinplaceofa documentvariableforthecomplextype. 3 SelecttheGenerate all element references as document type referencescheckboxif youwantIntegrationServertoreplaceallreferencestoglobalelementswith documentreferenceseveniftheelementisreferencedonlyonce.Integration ServergeneratesanISdocumenttypeforeachreferencedelement. LeavethecheckboxclearedifyouwantIntegrationServertoreplacean elementreferencewithadocumentreferenceonlyiftheelementisreferenced morethanonce.Whenanelementisreferencedonlyonce,Developerreplaces theelementreferencewithadocumentfield. 4 SelecttheappropriateoptiontospecifywhetherDevelopershouldprocess complextypesbyexpandingtheminlineintheeditororbygeneratingthem asseparateISdocumenttypes.ClickNext. IfyouwanttheISdocumenttypetousedifferentprefixesthanthosespecified intheXMLschemadefinition,selecttheprefixyouwanttochangeandentera newprefix.Repeatforeachnamespaceprefixthatyouwanttochange. TheprefixyouassignmustbeuniqueandmustbeavalidXMLNCName 6 ClickFinish.DevelopergeneratestheISdocumenttype(s)anddisplaysthem intheeditor.DeveloperalsogeneratesanISschemaanddisplaysitinthe Navigationpanel.

DevelopercreatestheISdocumenttypeandsavesitontheIntegrationServer. Developermightcreatemultipledocumenttypesdependingonthecontentsofthe sourcefileandtheprocessingoptionsyouselected.Ifyouwanttoaddoreditfieldsin theISdocumenttype,seeCreatinganEmptyISDocumentTypeonpage 251. Note: YoumightreceiveerrorsorwarningswhencreatinganISdocumenttype fromaDTDorXMLSchemadefinition.Formoreinformationabouttheseerrors andwarnings,seeValidationErrorsonpage 478.

258

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

Creating an IS Document Type from a Broker Document Type


Important! TheabilitytocreateapublishabledocumenttypefromaBrokerdocument typeisdeprecated. IfyourIntegrationServerisconnectedtoaBroker,youcancreateanISdocumenttype fromaBrokerdocumenttype.TheISdocumenttyperetainsthestructure,fields,data types,andpublicationpropertiesdefinedintheBrokerdocumenttype.Fordetailed informationabouthowaBrokerdocumenttypetranslatestoanISdocumenttypeand viceversa,seethePublishSubscribeDevelopersGuide. WhenyoucreateanISdocumenttypefromaBrokerdocumenttype,youessentially createapublishabledocumenttype.ApublishabledocumenttypeisanISdocumenttype withspecificpublishingproperties,suchasstoragetypeandtimetolive.Additionally,a publishabledocumenttypeonanIntegrationServerisboundtoaBrokerdocumenttype. 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, DeveloperwouldcreatethereferencedISschemapurchaseOrder. AnelementreferencedbyaBrokerdocumenttypemighthavethesamenameasan existingelementonyourIntegrationServer.However,elementnamesmustbeuniqueon theIntegrationServer.Developergivesyoutheoptionofoverwritingtheexisting elementswiththereferencedelements.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

259

9 Creating IS Schemas, IS Document Types, and Specifications

Important! IfyoudonotselecttheOverwrite existing elements when importing referenced elementscheckboxandtheBrokerdocumenttypereferencesanelementwiththe samenameasanexistingIntegrationServerelement,Developerwillnotcreatethe publishabledocumenttype. Important! Ifyouchoosetooverwriteexistingelementswithnewelements,keepin mindthatdependentsoftheoverwrittenelementswillbeaffected.Forexample, supposetheaddressdocumenttypedefinedtheinputsignatureofaflowservice deliverOrder.OverwritingtheaddressdocumenttypemightbreakthedeliverOrderflow serviceandanyotherservicesthatinvokeddeliverOrder. 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.

260

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

ClickFinish.DeveloperautomaticallyrefreshestheNavigationpanelanddisplays besidethedocumenttypenametoindicateitisapublishabledocumenttype. Notes:

YoucanassociateonlyoneISdocumenttypewithagivenBrokerdocumenttype. IfyoutrytocreateapublishabledocumenttypefromaBrokerdocumenttype thatisalreadyassociatedwithapublishabledocumenttypeonyourIntegration Server,Developerdisplaysanerrormessage. InthePublicationcategoryofthePropertiespanel,theBroker doc typeproperty displaysthenameoftheBrokerdocumenttypeusedtocreatethepublishable documenttype.Or,ifyouarenotconnectedtoaBroker,thisfielddisplaysNot Publishable.Youcannoteditthecontentsofthisfield.Formoreinformationabout thecontentsofthisfield,seethePublishSubscribeDevelopersGuide. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

261

9 Creating IS Schemas, IS Document Types, and Specifications

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

Assigning Universal Names to an IS Document Type


EveryserviceanddocumenttypeonawebMethodsIntegrationServerhasauniversal nameinadditiontoitsregularwebMethodsname.Auniversalnameisauniquepublic identifierthatexternalprotocols(suchasSOAP)usetoreferenceaserviceanddocument typeonawebMethodsIntegrationServer.Forinformationaboutassigningauniversal nametoservice,seeAssigningUniversalNamestoServicesandDocumentTypeson page 154.

262

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

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.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

263

9 Creating IS Schemas, IS Document Types, and Specifications

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.

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.

264

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

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.

Specifying Field Properties


Youcanspecifyadditionalpropertiesforthefield.Thesepropertiesarelocatedinthe Propertiespanel. Field properties

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

265

9 Creating IS Schemas, IS Document Types, and Specifications

OnthePropertiespanel,theGeneralcategorycontainsthepropertiesofthefieldandthe Constraintscategorycontainsvalidationconstraintsforthefield.(Formoreinformation aboutspecifyingvalidationconstraints,seeApplyingConstraintstoVariableson page 273.) 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. Note: Whenexecutingaservice,ifyouwantanullvaluetobeavailableasthefirst optioninthePick List,setthedev.uicontrols.picklist.putNullStringAtTop configurationparameterinthedeveloper.cnffilelocatedinthe Developer_directory\configdirectorytotrue.Bydefault,thisconfigurationparameter issettofalseandDeveloperaddsthenullvaluetotheendofthePick List. Pick List

266

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

267

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

IfyouwanttoreferenceanISdocumenttypefortheInputorOutputhalfofthe specification,dothefollowing: a IntheInputorOutputfield(dependingonwhichhalfofthespecificationyouwant toassigntheISdocumenttypeto),typetheISdocumenttypenameorclick to selectitfromalist.YoucanalsodraganISdocumenttypefromtheNavigation paneltotheboxbelowtheValidate inputorValidate outputcheckboxesonthe Input/Outputtab.ForinformationaboutcreatingISdocumenttypes,seeCreating anISDocumentTypeonpage 250. Tip! YoucanselectapublishabledocumenttypeoranISdocumenttypeto definetheinputoroutputhalfofthespecification.

268

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

9 Creating IS Schemas, IS Document Types, and Specifications

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 265.Fordetailsonapplyingconstraints,seeApplyingConstraintsto Variablesonpage 273.

Ifthefieldisadocumentoradocumentlist,repeatstepsbdtodefineeachofits members.Use field. toindenteachmemberbeneaththedocumentordocumentlist

OntheFilemenu,clickSave. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

269

9 Creating IS Schemas, IS Document Types, and Specifications

270

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

10

Performing Data Validation


272 273 278 281 281 282 283 284

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

271

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.

272

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

10 Performing Data Validation

Pipeline validation. ThevalidationengineinwebMethodsIntegrationServervalidates thestructureandcontentofthepipelineagainstanISdocumenttype. XML validation.ThevalidationengineinwebMethodsIntegrationServervalidatesthe structureandcontentofanXMLdocumentagainstanISschema. Thefollowingsectionsprovideinformationaboutperformingeachtypeofvalidation andinformationaboutapplyingconstraintstofields.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

273

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

IfyouwanttouseasimpletypefromanISschemaasthecontentconstraint, clicktheBrowsebutton.IntheBrowsedialogbox,selecttheISschema containingthesimpletypeyouwanttoapply.Then,selectthesimpletype youwanttoapplytothevariable.Toapplytheselectedtypetothevariable, clickOK. Ifyouwanttocustomizethecontenttypebychangingtheconstrainingfacets appliedtothetype,seeCustomizingaStringContentTypeonpage 276.

274

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

10 Performing Data Validation

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

Considerations for Object Constraints


ConstraintsforObjectandObjectlistvariablescorrespondtoJavaclasses,whereas constraintsforStringvariablescorrespondtosimpletypesinXMLschemas.Whenyou applyconstraintstoObjectsandperformvalidation,thedataisvalidatedasbeingofthe specifiedJavaclass.FordetailsontheJavaclassesyoucanapplytoanObjectorObject list,seeJavaClassesforObjectsonpage 431. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

275

10 Performing Data Validation

Customizing a String Content Type


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

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

276

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

10 Performing Data Validation

ClicktheCustomizebutton.Developermakestheconstrainingfacetfieldsbelowthe Content typelistavailablefordataentry(thatis,changesthebackgroundofthe constrainingfacetfieldsfromgreytowhite).Developerchangesthenameofthe contenttypetocontentType_customized. InthefieldsbelowtheContent typelist,specifytheconstrainingfacetvaluesyouwant toapplytothecontenttype.Formoreinformationaboutconstrainingfacets,see ConstrainingFacetsonpage 473. 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 431.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

277

10 Performing Data Validation

Performing Input/Output Validation


Ininput/outputvalidation,thevalidationengineinwebMethodsIntegrationServer validatestheinputsand/oroutputsofaserviceagainstthedeclaredinputandoutput parametersoftheservice.Ifyouspecifythatyouwanttovalidatetheinputstothe service,thevalidationenginevalidatestheserviceinputvaluesimmediatelybeforethe serviceexecutes.Ifyouspecifythatyouwanttovalidatetheoutputsoftheservice,the validationenginevalidatestheserviceoutputvaluesimmediatelyaftertheservice executes.Aninputoroutputvalueisinvalidifitdoesnotconformtotheconstraints appliedtotheinputoroutputparameter. Forinput/outputvalidation,theservicessdeclaredinputandoutputparametersactas theblueprintormodelagainstwhichinput/outputvaluesarevalidated.Toeffectively usetheinputandoutputparametersastheblueprintforvalidation,youneedtoapply constraintstotheparameters.Forinformationaboutapplyingconstraintstovariables, seeApplyingConstraintstoVariablesonpage 273.Forinformationaboutdeclaring serviceinputandoutputparameters,seeDeclaringInputandOutputParametersfora Serviceonpage 133.
.

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.

278

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

10 Performing Data Validation

Note: Ifyouspecifyinput/outputvalidationviatheINVOKEstepandaninputor outputvalueisinvalid,theserviceitselfdoesnotactuallyfail.Thevalidationengine validatesinputvaluesbeforewebMethodsIntegrationServerexecutestheservice.If theserviceinputisnotvalid,theINVOKEflowstepfortheservicefails.Similarly,the validationenginevalidatesoutputvaluesafterwebMethodsIntegrationServer executestheservice.Iftheserviceoutputisnotvalid,theINVOKEflowstepforthe servicefails.Whetherornottheentireflowservicefailswhenanindividualflowstep failsdependsontheexitconditionsfortheservice.Forinformationaboutspecifying exitconditions,seeUsingSEQUENCEtoSpecifyanExitConditiononpage 192.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

279

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.

280

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

281

10 Performing Data Validation

Inpipelinevalidation,anISdocumenttypeistheblueprintormodelagainstwhichyou validatethepipeline.TheconstraintsappliedtothevariablesintheISdocumenttype determinewhatcanandcannotbeincludedinthepipeline.Formoreinformationabout applyingconstraintstovariables,seeApplyingConstraintstoVariablesonpage 273. 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 284. Important! Thepub.schema:validateservicerequiresaparsedXMLdocumentasinput(an XMLnode).TheIntegrationServerparsesXMLdocumentsitreceivesviaHTTPor FTPautomatically.Youcanalsousethepub.xml:loadXMLNodeserviceorthe pub.xml:xmlStringToXMLNodetoparseanXMLdocument.Formoreinformationabout submittingXMLdocumentstoservices,seeSubmittingandReceivingXML Documentsonpage 365.Formoreinformationaboutthepub.xmlservices,seethe webMethodsIntegrationServerBuiltInServicesReference.

282

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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);

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

283

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.

284

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

285

10 Performing Data Validation

286

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11

Testing and Debugging Services


288 288 289 298 299 299 307 310 313 315 320

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

287

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: Debugservicesbysavingthepipeline,examiningthedata,andthenrestoringthe pipelineatalaterpointintime. Writearbitrarymessagestotheserverlog. Tracethepipelineatruntime. Modifyandsavethecontentsofthepipelineataspecifiedpoint. Note: ForinformationabouttestingBroker/localtriggersandpublishabledocument types,seethePublishSubscribeDevelopersGuide.

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

288

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 38. To test a service using Developer as the client 1 2 3 Opentheservicethatyouwanttotest. OntheTestmenu,selectRun.Ifyouhavenotyetsavedchangestotheservice, Developerpromptsyoutosavethem. Iftheservicehasinputparameters,typetheinputvaluesforeachvariableinthe InputdialogboxorclicktheLoadbuttontoretrievethevaluesfromafile.Formore information,seeEnteringInputforaServiceonpage 290. IfyouwantDevelopertopassemptyvariables(variablesthathavenovalue)tothe service,selecttheInclude empty values for String Types checkbox.Whenyouselectthis option,emptyStringsarepassedwithazerolengthvalue.Ifyoudonotselectthis option,emptyStringsarenotpassedtotheservice. Ifyouwanttosavetheinputvaluesthatyouhaveentered,clickSave.Inputvalues thatyousavecanberecalledandreusedinlatertests.Formoreinformationabout savinginputvalues,seeSavingInputValuestoaFileonpage 292. ClickOK.Developerinvokestheservicewiththespecifiedsetofinputvalues.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

289

11 Testing and Debugging Services

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

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.

290

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 289orTestingServicesfromaBrowseronpage 298. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

291

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 289orTestingServicesfromaBrowseronpage 298. EnterinputvaluesintotheInputdialogboxasdescribedinEnteringInputfora Serviceonpage 290. 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.

292

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

VariablesthatexistintheInputdialogbox,butnotinthefile,aresettonull. BesidesloadingvaluesthatweresavedfromtheInputdialogbox,youcanalsoload valuesthatweresavedusingpub.flow:savePipelineToFileserviceortheSave Pipeline commandsontheFilemenu.Inaddition,youcanchangevaluesinthepipeline duringtesting.Forinformationaboutsavingthestateofthepipeline,seeSavingand RestoringthePipelineonpage 315.Forinformationaboutmodifyingvaluesinthe pipeline,seeModifyingtheCurrentPipelineonpage 313. To load input values that have been saved to a file 1 2 3 OpentheserviceandexecuteitasdescribedinTestingServicesfromDeveloperon page 289. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

293

11 Testing and Debugging Services

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

294

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 inamessagebox. YoucanclicktheDetailsbuttontodisplaythecallstackandthepipelineatthepoint wheretheerroroccurred. Note: TheIntegrationServerlogsdetailsaboutruntimeexceptions,includingthecall stack,thestacktrace,andthecauseoftheerror,intheIntegrationServererrorlog.This informationisusefulfordebuggingservicesinaproductionenvironment.Youcan controlthelevelofdetailwrittentothelogbysettingthe watt.server.deprecatedExceptionLoggingparameter.Formoreinformationaboutthis parameterandtheIntegrationServererrorlog,seeAdministeringwebMethodsIntegration Server.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

295

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

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.

296

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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).Iftheparentitselfthrowsthe exception,itwillbetheonlyentryinthecallstack. Note: ServicesinvokedfromwithinaJavaservicearenotreportedinthecallstack, eveniftheythrowtheexception.

The Pipeline Dump


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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

297

11 Testing and Debugging Services

Testing Services from a Browser


YoucanusetheRun in BrowsercommandinDevelopertotestaservicefromabrowser (thatis,tosimulateabrowserbasedclient).Whenyouusethiscommand,Developer promptsyoufortheservicesinputvalues,buildstheURLnecessarytoinvokethe servicewiththeinputsyouspecify,andthenpassestheURLtoyourbrowser.Whenyou usethiscommandtotestaservice,yourbrowser(notDeveloper)actuallyinvokesthe serviceandreceivesitsresults. 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 290. Note: OnlyStringsandStringlistsarepassedtothebrowser. 4 Ifyouwanttopassemptyvariables(variablesthathavenovalue)totheservice, selecttheInclude empty values for String Typescheckbox.Whenyouselectthisoption, emptyStringsarepassedwithazerolengthvalue.Ifyoudonotselectthisoption, Developerexcludesemptyvariablesfromthequerystringthatitpassestothe browser. Ifyouwanttosavetheinputvaluesthatyouhaveentered,clickSave.Inputvalues thatyousavecanberecalledandreusedinlatertests.Formoreinformationabout savinginputvalues,seeSavingInputValuestoaFileonpage 292. ClickOK.DeveloperbuildstheURLtoinvoketheservicewiththeinputsyouhave specified,launchesyourbrowser,andpassesittheURL.

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

298

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Testing Services that Expect XML Documents as Input


IfyourserviceexpectsanXMLdocumentasinput(thatis,ittakesanodeasinput),you cantestitusingtheSend XML Filecommand.Thiscommandpromptsyouforthenameof theXMLfileandsubmitsthefiletotheservice,emulatingthewayinwhichtheservice wouldexecuteifanXMLdocumentwerepostedtoit. TotestaservicebysendinganXMLfiletotheservice,youmusthaveReadaccesstothe service. 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 293. Iftheserviceexperiencesanerror,anerrormessagedisplays.ClickDetailsinthe messageboxtoviewthecallstackandthestateofthepipelinewheretheerror occurred.Foradditionalinformationabouterrorsthatoccurwhiletestinga service,seeRunTimeExceptionsonpage 295.

Working in Debug Mode


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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

299

11 Testing and Debugging Services

Entering Debug Mode


Youautomaticallyenterdebugmodewhenyouselectanyofthefollowingcommands fromtheTestmenu: Command Trace Description Executesflowstepsoneafteranothertotheendoftheserviceand visuallymarksstepsastheyexecute.Forinformationaboutusing thiscommand,seeUsingtheTraceToolsonpage 302. Executesflowstepsoneafteranotheruptoaspecifiedpointand visuallymarksstepsastheyexecute.Forinformationaboutusing thiscommand,seeUsingtheTraceToolsonpage 302. Executesflowstepsoneafteranothertotheendoftheserviceand visuallymarksstepsastheyexecute,includingstepsinchildflows. Forinformationaboutusingthiscommand,seeTracingintoa ChildFlowonpage 303. Executesthenextflowstepandthenhalts.Forinformationabout usingthiscommand,seeUsingtheStepToolsonpage 304. OpensachildfloworaMAPstepsothatyoucandebugthe individualflowstepswithinit.Forinformationaboutusingthis command,seeSteppingThroughaChildFlowonpage 305and UsingtheStepToolswithaMAPSteponpage 306.

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.

300

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

301

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

302

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 307. 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,youmaydo anyofthefollowing:

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

Tracing into a Child Flow


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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

303

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 121. Note: Whenyoustepintoachildflow,Developerdisplaysthechildflowintheeditor. Notethatatanypointwhilesteppingthroughaflowservice,youcandoanyofthe following: ExaminethecontentsoftheResultspanel. Modify,save,and/orrestorethecontentsoftheResultspanel. SelectastepintheflowserviceanduseTrace to Heretotracetothatpoint.

304

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 Through 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 305orTotracetoaspecified pointonpage 303ifyouneedproceduresforthisstep. OntheTestmenu,clickStep Into.Developeropensthechildflowserviceandselects (butdoesnotexecute)thefirststep. OntheTestmenu,clickSteptoexecutethefirststepinthechildservice.Repeatthis stepforeachflowstepthatyouwanttoindividuallyexecutewithinthechild. Ifyouwanttoreturntotheparentflowservicewithoutsteppingthroughtheentire child,clickStep OutfromtheTestmenu.Thiscommandwilltracetheremainingsteps inthechildflow,returntotheparent,andthenselect(butnotexecute)thenextstep intheparentflow. Notes:

2 3 4

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

305

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 305orTo tracetoaspecifiedpointonpage 303ifyouneedproceduresforthisstep. 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,Developer tracestheremainingstepsintheMAPandreturnstotheparentautomatically. IfyouselectSteponthelasttransformerintheMAP,Developerautomatically executesthattransformerandreturnsyoutotheparentflow. YoucanuseStep Intotostepintoatransformerthatisaflowservice. IfyouselectStep Intoonatransformerthatisnotaflowservice,Stepisexecuted.

306

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Setting Breakpoints
Abreakpointisapointinaflowservicewhereyouwantprocessingtohaltwhenyou executethatflowservicewithcertaindebugmodes.Breakpointscanhelpyouisolatea sectionofcodeorexaminedatavaluesataparticularpointintheexecutionpath.For example,youmightwanttosetapairofbreakpointsbeforeandafteraparticular segmentofaflowsothatyoucanexaminethepipelineontheResultspanelbeforeand afterthatsegmentexecutes. 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 142. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

307

11 Testing and Debugging Services

To clear a breakpoint from a flow step 1 2 3 Opentheflowserviceinwhichyouwanttoclearabreakpoint. Intheeditor,selectthebreakpointstep. OntheTest menu,clickClear Breakpoint.Thestepsiconreturnstoitsnormalcolor, indicatingthatitisnolongerabreakpoint. OR 1 2 3 OntheTestmenu,clickBreakpointstodisplaythecurrentlistofbreakpointsonthe currentserver. Inthelist,selectthebreakpointthatyouwanttoclear. ClickRemove.

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 Opentheflowserviceinwhichyouwanttoclearabreakpoint. Intheeditor,selecttheMAPstepthatcontainsthetransformerfromwhichyouwant toclearabreakpoint. iconappearsnexttothetransformer

308

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

3 4

OnthePipelinetab,selectthetransformerfromwhichyouwanttoclearabreakpoint. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

309

11 Testing and Debugging Services

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

310

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

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.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

311

11 Testing and Debugging Services

To disable a transformer in a MAP step 1 2 3 4 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheMAPstepcontainingthetransformerthatyouwanttodisable. OnthePipelinetab,selectthetransformeryouwanttodisable. OntheComposemenu,clickDisable Step. Thetransformerdims,indicatingthatitisdisabled. 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,selecttheINVOKEorMAPstepthatcontainsthelinkwiththe conditionyouwanttodisable. OnthePipelinetab,selectthelinkwiththeconditionthatyouwanttodisable. IntheGeneralcategoryofthePropertiespanel,settheEvaluate copy conditionproperty toFalse.

312

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

To enable a condition placed on a link between variables 1 2 3 4 Opentheflowservicethatyouwanttoedit. Intheeditor,selecttheINVOKEorMAPstepcontainingthelinkwiththecondition youwanttoenable. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

313

11 Testing and Debugging Services

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

314

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Saving and Restoring the Pipeline


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

Saving the Results


Youcansavethepipelinetoafile,whichyoucanusetorestorethepipelinetoitscurrent stateatalaterpointintime.Thisisusefulwhenyouwanttotestanotherserviceagainst thecurrentsetofpipelinevaluesorifyouwanttorestorethepipelinetothisexactstate laterinthedebuggingprocess.Therearethreewaystosavethecontentsofthepipeline: YoucanmanuallysavethecontentsoftheResultspanelwhenyourunordebuga serviceusingDeveloper. AutomaticallysavethepipelineatruntimeusingthePipeline Debug property. Youcanprogrammaticallysavethepipelineatruntimebyinvoking pub.flow:savePipelineToFileatthepointwhereyouwanttocapturethepipeline. Whenyousaveapipeline,itissavedinafileinXMLformat.Thefileyoucreatecanbe usedto: ManuallyloadthepipelineintoDevelopersResultspanel. AutomaticallyloadthepipelineatruntimeusingthePipeline Debugproperty. Dynamicallyloadthepipelineatruntimeusingthe pub.flow:restorePipelineFromFile service. LoadasetofinputvaluesintotheInputdialogboxwhentestingaservicewith Developer. Youcanviewapipelinefilewithanordinarytexteditor.Whensavingthepipeline,keep thefollowingpointsinmind: OnlyXMLcodablevariablesaresaved.Thisincludes,Strings,Stringlists,String tables,documents,anddocumentlists.VariablesthatarenotXMLcodablearenot saved. Emptyvariablesandnullvariablesaresaved.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

315

11 Testing and Debugging Services

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

Automatically Saving the Pipeline at Run Time


YoucanautomaticallysavethepipelineforaflowserviceatruntimebyusingthePipeline Debugproperty.ThePipeline DebugpropertyislocatedintheRuntimecategoryofthe Propertiespanel.WhenthepropertyissettoSave,theserversavestheentirecontentsof thepipelinetoafilewhentheflowserviceisexecuted. FormoreinformationaboutusingthePipelineDebugpropertytosavethepipeline,see UsingthePipelineDebugPropertyonpage 149.

316

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Manually Saving the Pipeline at Run Time


Usethefollowinggeneralstepstosavethepipelineprogrammatically.Youcanusethis techniquetocapturethepipelinefromaflowserviceorwithinaJavaservice. To manually save the pipeline at run time 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. WiththerestoreoptionsfromthePipeline Debugproperty. Withthepub.flow:savePipelineToFileserviceatruntime. FromtheInputdialogboxwhenyouaretestingaservicewithDeveloper. Restoringapipelineisusefulwhenyousimplywanttoinspectthevaluesinaparticular pipelinefile(perhapsonethatcontainsthepipelinefromafailedservice).Additionally,it isusefulinmanytestingsituations.Forexample,youcanuseittoreplacetheexisting pipelinewithadifferentsetofvalueswhensteppingthoughaflowservicewiththe debuggingtools.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

317

11 Testing and Debugging Services

Therearethreewaystorestorethecontentsofthepipeline: YoucanmanuallyloadthesavedpipelineintotheResultspanelinDeveloper. YoucanautomaticallyloadthesavedpipelineatruntimebyusingthePipeline Debug property. Youcanprogrammaticallyloadasavedpipelineatruntimebyinvoking pub.flow:restorePipelineFromFileatthepointwhereyouwanttomodifythepipeline.

Loading a Saved Pipeline into the Results Panel


UsethefollowingproceduretoloadapipelinefileintotheResultspanel. WhenyouloadapipelinefileintotheResultspanel,thecontentsofthepipelinefile completelyreplacesthecurrentpipeline.Ifyouwanttomergethecontentsofthefilewith theexistingpipeline,usethepub.flow:restorePipelineFromFileserviceinsteadandsetitsmerge parametertotrue.Forprocedures,seeManuallyLoadingaSavedPipelineatRun Timeonpage 319. 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.

318

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Automatically Loading a Saved Pipeline at Run Time


Youcanautomaticallyrestorethepipelineforaflowserviceatruntimebyusingthe Pipeline Debugproperty.ThePipeline DebugpropertyislocatedintheRuntimecategoryof thePropertiespanel.Torestorethepipelineusingthisproperty,youcanchoosetoeither overrideormergetheexistingpipelinewiththecontentsfromapreviouslysavedfile. Whenarestoreoptionisselectedandtheserviceisexecuted,theserverloadsthepipeline file,folderName.serviceName.xml,fromtheIntegrationServer_directory\pipelinedirectory. FormoreinformationaboutusingthePipelineDebugpropertytorestorethepipeline, seeUsingthePipelineDebugPropertyonpage 149.

Manually Loading a Saved Pipeline at Run Time


Usethefollowinggeneralstepstoloadapipelinefileprogrammatically.Youcanusethis techniquefromaflowserviceorfromaJavaservice. 1 2 3 Opentheservice. Invokepub.flow:restorePipelineFromFileatthepointwhereyouwanttoloadthepipeline file. 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 true

merge

To... Replacetheexistingpipelinewiththeone fromthefile. Mergethecontentsofthefileintotheexisting pipeline.

4 5

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

Foradditionalinformationaboutpub.flow:restorePipelineFromFile,seethewebMethods IntegrationServerBuiltInServicesReference.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

319

11 Testing and Debugging Services

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

320

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

The Contents of the Server Log


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

Server Debug Levels


Theamountandtypeofinformationthatisloggedbytheserverisdeterminedbythe debuglevelunderwhichtheserveroraspecificfacilitywithintheIntegrationServeris operating. Youcanspecifytheserverdebuglevelwhenyoustarttheserver.Thedebuglevelcan rangefromOff,wherenothingislogged,toTrace,inwhichtheserverkeepsanextremely detailedlog.Formoreinformationabouttheavailablelogginglevels,seethewebMethods AuditLoggingGuide. 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,seewebMethodsAuditLoggingGuide. Important! DebuglevelsaboveInfoproducelotsofdetailandcanquicklygeneratean extremelylargelogfile.YoushouldnotrunyourserverattheDebugorTracelevels exceptforbriefperiodswhenyouareattemptingtotroubleshootaparticularissue. Youmayalsooptionallyredirectserverlogmessagestotheconsoleinsteadofafile usingthelog nonestartupswitch.Formoreinformationaboutthisswitchand debuglevels,seeStartingthewebMethodsIntegrationServerinAdministering webMethodsIntegrationServer.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

321

11 Testing and Debugging Services

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

322

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

11 Testing and Debugging Services

Key function

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

3 4

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

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). Thefollowingexampleshowsthestartandendpipelinethatwaswrittentotheserver logwithpub.flow:tracePipeline.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

323

11 Testing and Debugging Services

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

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 321. 3 4 Savetheservice.(IfyouareusingyourownIDE,youwillneedtorecompilethe service,reregisteritonwebMethodsIntegrationServer,andreloaditspackage.) Executetheservice.Foradditionalinformationaboutpub.flow:tracePipeline,seethe webMethodsIntegrationServerBuiltInServicesReference.

324

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12

Building Coded Services


326 328 328 329 335 341 345 345

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

325

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.ThevaluescanbeanyJava objects(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; }

326

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 { myIDataObject = IDataFactory.create(); IDataCursor myCursor = myObject.getCursor(); myCursor.insertAfter("VA", new Double("0.045")); myCursor.insertAfter("MD", new Double("0.05")); myCursor.insertAfter("DE", new Double("0.0")); }

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

327

12 Building Coded Services

Building Services Using Java


SinceJavaisthenativelanguageofservices,itistheeasiestlanguageinwhichtobuilda service. webMethodsDeveloperprovidesanIntegratedDevelopmentEnvironment(IDE)that youcanusetocreate,compile,andpublishJavaservices.TheIDEautomatically generatesanappropriatelystructuredsourcefilethatyousimplyfillinusingthebuilt ineditor.Whenyousavethesourcefile,theIDEautomaticallycompilesitandregistersit ontheserver. YoucanuseDevelopersIDEforcreatingsmall,simpleservices.HoweverDesignerisa muchbetterIDEforcreatingJavaserviceswhethersmallorlarge.Formoreinformation aboutcreatingJavaservicesusingDesigner,seethewebMethodsDesignerOnlineHelp. Alternatively,youcanuseyourownJavaIDE.WhenyouuseyourownIDE,youmust createallofthecodeyourself,andmanuallycopyandregistertheclassfileontheserver. webMethodsIntegrationServerprovidesutilitiestopublishservicesyouwriteinyour ownIDE.FormoreinformationaboutcreatingJavaserviceswithoutusingDeveloper, seeBuildingJavaServiceswithYourOwnIDEonpage 335.

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. WhenyoubuildaJavaservicewithDeveloperorDesigner,yourserviceisautomatically combinedintotheclassfileassociatedwiththefolderinwhichyoucreatedit.However, ifyoubuildaJavaserviceinyourownIDE,youwillneedtoaddtheclassfiletothe serveryourself.And,ifyouwantthatservicetoberecognizedbyDeveloperorDesigner, youmustinsertspecialcommentcodeinyoursourcecode.

328

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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 333. Create the Java service using Developer. Duringthisstage,youwriteyour programinDevelopersIDE.Forinformationaboutthisstage,see CreatingaJavaServicewithDevelopersIDEonpage 332. Specify the services run-time parameters. Duringthisstage,youassign parametersthatconfiguretheruntimeenvironmentforthisservice.For informationaboutthisstage,seeSettingRunTimeOptionsforaJava Serviceonpage 335.

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 76. Make sure the folder in which you want to create the service already exists. Ifthefolderdoes notalreadyexist,useDevelopertocreateit.Fordetails,seeCreatingNewElements onpage 45. Make sure that all Java and C services are unlocked or locked by you in the folderinwhichyou wanttocreatethenewservice.Fordetails,seeLockingJavaandC/C++Serviceson page 101. Important! AllJavaservicesthatbelongtothesamefolderresideinthesameJavaclass file.Thisclasshasthesamenameasthefolder.

Using the Developer IDE


IntheDeveloperIDE,youusetheJavaserviceeditoranditsSharedtabtocreateyour sourcecode.

The Java Service Editor


YouusetheJavaserviceeditortobuildthebodyofyourprogram.Itislikeatemplate youfillinwithcustomJavacode.Standardblocksofrequiredcodeappearinthe shadedareasatthetopandbottomofthetab.Youcannotalterthecodeintheseareas.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

329

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.

330

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

331

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 333. 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(fully qualifiedifnecessary). Thenamesofinterfaceswithinthesuperclassthatthisclass implements.Takethefollowingstepstospecifyeachinterfacethat youwanttoimplement: Click toaddanewrowtothelist.

Implements

TypethenameofavalidJavaclassname(fullyqualifiedif necessary).Youdonotneedtotypetheimplementskeyword.

332

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

Use this field... Imports

To specify... 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. Forexample,iftheInput/Outputtabfortheservicedefinesthefollowingvariablesasinput andoutput: Input Variable Name State Amount Output Variable Name Tax Type String String Type String

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

333

12 Building Coded Services

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 136. IfyouwanttogeneratecodeforasubsetofthevariablesontheInput/Outputtab,select thosevariables. OntheToolsmenu,clickGenerate Code. OntheCodeGenerationdialogbox,selectFor implementing this serviceandclickNext. Specifythefollowingoptions. Under this... Specification Which fields? 7 8 Specify... Whetheryouwanttogeneratecodefortheinputvariables,the outputvariables,orboth. Whetheryouwanttogeneratecodeforallvariablesinthe Input/Outputtaborjusttheselectedvariables.

3 4 5 6

ClickFinish.DevelopergeneratescodeandplacesitontheClipboard. PastethecontentsoftheClipboardintoyoursourcecode.

334

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

Setting Run-Time Options for a Java Service


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

Building Java Services with Your Own IDE


TheremightbetimeswhenyouwanttouseyourownIDEinsteadofDeveloperor DesignertobuildaJavaservice.

The Namespace Directory


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

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

335

12 Building Coded Services

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

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.

336

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

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 332). Specify the input and output parameters (signature) of the service.Duringthis stage,youdefinetheservicesinputsandoutputs(ifyouknowthese).You canuseDevelopertogeneratetheinputandoutputcodethatyoucan pasteintoyourprogram(seeGeneratingJavaCodefromServiceInput andOutputParametersonpage 333). Create the Java service using your IDE. Duringthisstage,youwriteand compileyourprograminyourIDE.Formoreinformationaboutthis stage,seeWritingtheSourceCodeforaServiceonpage 336. Saving and compiling your code using jcode (optional). Duringthisstage,you canmakeyoursourcecodeavailableforeditingbyDeveloperbyusing thejcodeutility.Forinformation,seeCommentingCodeforthe webMethodsIntegrationServeronpage 337. Publish the service to the webMethods Integration Server.Duringthisstage,you registeryourserviceontheIntegrationServerusingthejcodeutility.For information,seeUsingthejcodeUtilityonpage 338.

Stage 2

Stage 3

Stage 4

Stage 5

Commenting Code for the webMethods Integration Server


ToinstallyourfinishedserviceonthewebMethodsIntegrationServer,youusethejcode utility.Tousethisutilitysuccessfully,youmustannotateyoursourcecodewithjcode tags(speciallyformattedJavacomments)tomarkthefollowingsegmentsofcode: Imports Sharedcodewithintheclass Servicedefinitionsandserviceinputsandoutputs

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

337

12 Building Coded Services

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.

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

338

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

339

12 Building Coded Services

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

340

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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/C++ compilerinstalledonthehostwherewebMethods IntegrationServerininstalled. Make sure that you have completed the proceduresspecifiedin IntegrationServer_directory/sdk/c/READMEand/or IntegrationServer_directory/sdk/cpp/doc/READMEtobuildtheplatformsupport librariesneededbyIntegrationServerandDeveloper. Make sure the package in which you want to create the service already exists.Ifthepackage doesnotalreadyexist,createitusingwebMethodsDeveloper.Formoreinformation aboutcreatingapackage,seeCreatingaPackageonpage 76.(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 45. 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. Note: IfyouarerunningtheIntegrationServerasanNTservice,youmust completeoneofthefollowing: SettheWindowssystemenvironmentvariablePATHtoinclude IntegrationServer_directory\lib OR CopythewmJNI.dllandwmJNIc.dllfileslocatedin IntegrationServer_directory\libtotheIntegrationServer_directorydirectory

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

341

12 Building Coded Services

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. DevelopergeneratesalltheJavacodeneededtosuccessfullycallyourCprogram.You mayaddyourowncustomcodetotheCserviceeditororitsSharedtabifyouwantto executeanyspecialproceduresbeforeoraftertheCprogramiscalled,butotherthan that,thisservicecontainseverythingyouneed. The C service editor contains code that calls the Java wrapper for the C program

342

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

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

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

Building the C/C++ Source Code


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

ThenamesofthefileswillmatchtheservicenameyouspecifiedinDeveloper.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

343

12 Building Coded Services

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.You canalsorefertowebMethodsCAPIforinformationabouthowtousethe webMethodsC/C++APItomakethedatainyourserviceavailabletootherservices. ThisfileislocatedinDeveloper_directory\doc\api\c\index.html. 4 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 342. 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.

344

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

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 345. Create services using COM. webMethodsIntegrationServerincludeslibrariesforusein yourownVisualBasicorVisualC++code.TheyallowyoutocreateCOMobjectsthat performworkonwebMethodsdatastructures.Theseobjects(compiledintoActiveX DLLsorEXEs)canthenberegisteredasnativeservices,indistinguishablefromtheir Javacounterparts.

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

345

12 Building Coded Services

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. TheservicewillreturnareferencetotheobjectcalledpDispatchorthrowanerrorifthe objectcannotbecreated. Tip! TheWmWin32packageisinstalledwiththeIntegrationServeronMicrosoft Windowsplatformsbut,bydefault,isnotenabled.Toviewthepackageandaccessits serviceswithinDeveloper,firstenableitusingtheIntegrationServerAdministrator.

346

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

12 Building Coded Services

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

347

12 Building Coded Services

348

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13

Creating Client Code


350 350 353 355 358 360

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

349

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:

350

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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:


Software AG_directory\common\lib\wm-isclient.jar Software AG_directory\common\lib\ext\mail.jar

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

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

351

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

352

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

353

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

354

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13 Creating Client Code

Building a Visual Basic Client


YoucanuseDevelopertogenerateVisualBasicclientcodethatinvokesaservice. Developercreatesfilesthatcontainthelayoutandthecodeforyourapplication.

Assumptions
webMethodsIntegrationServerisrunning. VisualBasicVersion6isinstalled. webMethodsTypeLibraryisinstalled. Note: ThewebMethodsTypeLibraryisaCOMobjectthatVisualBasicusestointeract withwebMethodsIntegrationServer.ThewebMethodsTypeLibraryisautomatically installedwhenyouinstallDeveloper.

Environment Setup
YoursystemPATHenvironmentvariablemustincludethefollowingdirectory: Software AG_directory\jvm\win150\jre\bin\client OR Software AG_directory\jvm\win160\jre\bin\client

Limitations
TheclientcodethatDevelopergeneratessupportsonlyinputvaluesandoutput valuesoftypeString,Stringlist,andStringtable. TheclientcodethatDevelopergeneratesdoesnotsupportmultipleinputoroutput variableswiththesamename. WhenDevelopergeneratesclientcode,Developerreplacesanyspaceinavariable namewithanunderscore. Ifyouwanttooverridetheselimitations,youwillneedtomodifytheclientcodethat Developergenerates.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

355

13 Creating Client Code

Procedure
UsethefollowingproceduretohaveDevelopergenerateVisualBasicclientcodethat invokesaservice. To generate Visual Basic 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,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.

356

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13 Creating Client Code

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. Containslayoutandcodethatisusedifanyoftheinput valuesfortheserviceareoftypeStringtable. Containscodethatisspecifictothesampletemplatethat Developergenerates.

frmSetup.frm

frmStringInput.frm frmTableInput.frm wmSampleLib.bas

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

357

13 Creating Client Code

Building an Excel Client


YoucanuseDevelopertogenerateclientcodethatexecutesaservicefromaMSExcel spreadsheet.

Assumptions
webMethodsIntegrationServerisrunning. Excel97orExcel2000isinstalled. webMethodsTypeLibraryisinstalled. Note: ThewebMethodsTypeLibraryisaCOMobjectthatVisualBasicusestointeract withwebMethodsIntegrationServer.ThewebMethodsTypeLibraryisautomatically installedwhenyouinstallDeveloper.

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.

358

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13 Creating Client Code

ClickFinish. Developergeneratesseveralfiles,includingtheserviceNameReadMe.txtfile.Thisfile containsdetailedinformationaboutallgeneratedfiles.

CopythewmXLTemplate.xlsfilethatDeveloperprovidestothedirectorythat containstheclientcodethatDevelopergenerated.ThewmXLTemplate.xlsfileis locatedintheDeveloper_directory\support\Exceldirectory. OpenthewmXLTemplate.xlsfile.Whenpromptedtoindicatewhetheryouwantto enablemacros,selectEnable Macros. FollowtheinstructionsinthewmXLTemplate.xlsfiletocompleteyourclient application.SeetheServiceNameReadMe.txtfileforinformationaboutdeployingyour clientapplication.

8 9

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

359

13 Creating Client Code

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,refertoAdministeringwebMethodsIntegrationServer. Note: YoucannotuseDevelopertogeneratebrowserbasedclients.

Assumptions
webMethodsIntegrationServerisrunning. Theinputvaluesfortheservicesyouwanttoinvokearedetermined.Youwillneedto includetheinputvaluesintheURLthatyouusetoinvokeaservice.

Limitations
WhenyoutestaserviceusingtheRun in Browsercommand,onlyinputvaluesofthetype StringandStringlistwillbepassedtotheservice.Inputvaluesofthetypedocument, documentlist,Object,andObjectlistwillnotbedisplayedwhentheWebpageisserved.

360

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

13 Creating Client Code

Invoking Services with a URL


First,buildyourWebpagesusinganytoolyouchoose.ToinvoketheURL,useeitherthe HTTPGETorthePOSTmethod.Ineithercase,useaURLsimilartothefollowing:

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

361

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

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

362

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

363

13 Creating Client Code

Output from the Service


Bydefault,webMethodsIntegrationServerdisplaystheoutputfromaserviceinaHTML Webpage,usingatabletorendertheoutputvalues.However,youcanformattheoutput usingoutputtemplates.Youcanuseanoutputtemplatethatformatstheoutputfromone serviceandincludesaURLthatinvokesanotherservice.Formoreinformationabout outputtemplates,seeAssigninganOutputTemplatetoaServiceonpage 138.

364

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14

Submitting and Receiving XML Documents


366 366 367 369 371 374

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML in $xmldata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

365

14 Submitting and Receiving XML Documents

Overview
YoucansubmitXMLdocumentstothewebMethodsIntegrationServerfromaclient, andhavetheIntegrationServerreceiveXMLdocumentswithservicesthatyouwrite. TheIntegrationServerprovidesthefollowingautomatedmechanismsforreceiving arbitraryXMLdocuments,parsingthem,andpassingthemasinputtoaspecified service. AclientsubmitsanXMLdocumenttoaserviceinaStringvariable(ofanyname), whichthetargetserviceconvertsintoanodeusingpub.xml:xmlStringToXMLNode. AclientsubmitsanXMLdocumenttoaserviceinaspecialStringvariablenamed $xmldata,andwebMethodsIntegrationServerautomaticallyparsesthevariableand passesittotheserviceasanode. AclientpostsanXMLdocumenttoaserviceviaHTTP. AclientFTPsanXMLdocumenttoaservice. AclientemailsanXMLdocumenttoaservice. AclientsendstheXMLdocumentasanemailattachment.

Submitting and Receiving XML in a String Variable


OnewaytosubmitanXMLdocumenttothewebMethodsIntegrationServeristopass theentireXMLdocumenttoaserviceinaStringvariable.Whenyouusethisapproach, youshouldcodethetargetservicetoexecutepub.xml:xmlStringToXMLNodetoconvertthe Stringvariable(thatis,theXMLdocument)toanode.OncetheXMLdocumentis representedasanode,itexistsinaformthatcanbequeriedorconvertedtoanIData object.ForinformationaboutusingxmlStringToXMLNode,seethewebMethodsIntegration ServerBuiltInServicesReference.

Example: Submitting XML in a String


ThefollowingcodefragmentshowshowaJavaclientmightsubmitanXMLdocumentto aservicecalledpurch:postOrderonwebMethodsIntegrationServer.Inthisexample,the client: 1 2 3 LoadstheXMLdocumentintoaString PutstheStringintotheelementordersinanIDataobjectnamedinputs Invokespurch:postOrderontheserveratlocalhost:5555

366

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14 Submitting and Receiving XML Documents

import import import import public

com.wm.app.b2b.client.*; com.wm.util.*; com.wm.data.*; java.io.*; class ArbitraryXMLClient . . . //--Load XML into orders string String orders = YourLoadXMLMethod(orderFile); //--Put input values into IData object IData inputs = IDataFactory.create(); IDataCursor inputsCursor = inputs.getCursor(); inputsCursor.insertAfter("orders", orders); inputsCursor.insertAfter("authCode", authCode);

//--Submit request to server c.connect("localhost:5555", "null", null); IData outputs = c.invoke("purch", "postOrder", inputs); c.disconnect(); . . .

Example: Receiving XML in a String


Ontheserver,thereceivingserviceshouldbecodedtopasstheXMLintheString variabletopub.xml:xmlStringToXMLNode.Thisproducesanodethatcanbesubsequently queriedorconvertedtoanIDataobject. Inthepreviousexample,purch:postOrdershouldbecodedtopasstheXMLdocumentin orderstopub.xml:xmlStringToXMLNode.Forinformationabouttheservicesthatyoucanuse tomanipulatenodes,seepub.xml:queryXMLNodeandpub.xml:xmlNodeToDocumentinthe webMethodsIntegrationServerBuiltInServicesReference.

Submitting and Receiving XML in $xmldata


SubmittinganXMLdocumenttowebMethodsIntegrationServerusing$xmldatais similartosubmittingitasaStringvariable,butinthiscase,theservicereceivingtheXML documentdoesnotneedtoincludeaparsingstep;webMethodsIntegrationServer automaticallyparsesthecontentsof$xmldata. Thename$xmldatahasspecialmeaningtotheIntegrationServerinthatitassumesthe valueofthisvariableisanXMLdocument.Whenitreceivesarequestthatincludesan inputvariablenamed$xmldata,theserverautomaticallyparsesthecontentsofthat variable,producinganXMLnodethatcanbeusedbyanyservicethattakesanodeas input.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

367

14 Submitting and Receiving XML Documents

Example: Submitting and Receiving XML in $xmldata


ThefollowingexampleshowsaclientapplicationthatreadsanXMLdocumentfroma file,assignsthetextinthefileto$xmldataandthenpasses$xmldatatoaservicecalled sales:getOrder.
import import import import com.wm.app.b2b.client.*; com.wm.util.*; com.wm.data.*; java.io.*;

public class ArbitraryXMLClient { public static void main(String args[]) throws Exception { //--Read XML document from a specified file (or from stdin) Context c = new Context(); IData inputs = IDataFactory.create(); IDataCursor inputsCursor = inputs.getCursor(); Reader in = null; if(args.length > 0) { in = new InputStreamReader(new FileInputStream(args[0])); } else { in = new InputStreamReader(System.in); } char[] buf = new char[8192]; int count = 0; StringBuffer sb = new StringBuffer(); while((count = in.read(buf)) != -1) { sb.append(buf, 0, count); } //--Assign XML document to string variable String xmldata = sb.toString(); //--Put XML document into $xmldata in IData object inputsCursor.insertAfter("$xmldata", xmldata); //--Submit request to server c.connect("localhost:5555", "null", null); IData outputs = c.invoke("sales", "getOrder", inputs); c.disconnect(); //--Display the returned output values System.out.println(outputs); }

Theserviceinvokedbythisclientmustbeaservicethattakesanodeasaninputvariable (forexample,queryXMLNode,xmlNodeToDocument),becausethisiswhatwebMethods IntegrationServerproduceswhenitreceivesthisrequest. Important! ThisexampleshowsaJavabasedclient;however,anytypeofISclient (evenabrowserbasedclient)canbeused.Withabrowserbasedclient,youwould posttheXMLdocumentasthevalueportionofa$xmldata=valuepair.Youwould mostlikelyconstructtheXMLdocumentwithJavascript.Youmaypostother name=valuepairswiththerequest.

368

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14 Submitting and Receiving XML Documents

Submitting and Receiving XML via HTTP


AclientcanpostanXMLdocumenttoaservicethatreceivesitviaHTTP.Tousethis approach,youmusthaveaclientthatcan: Sendastringofdata(anXMLdocument)towebMethodsIntegrationServerusing theHTTPPOSTmethod. AND SetthevalueoftheContent-Typerequestheaderfieldtotext/xml. WhenwebMethodsIntegrationServerreceivesanHTTPPOSTrequestwhereContentTypeistext/xml,itautomaticallyparsesthebodyoftherequest(theXMLdocument)and passesitasanodetotheservicespecifiedintherequestsURL.

Client Requirements
SincemostbrowsersdonotallowyoutomodifytheContentTypeheaderfield,theyare notsuitableclientsforthistypeofsubmission.Clientsthatyoumightusetosubmitan XMLdocumentinthismannerarePERLscripts(whichallowsyoutobuildandissue HTTPrequests)orthewebMethodsIntegrationServerservice,pub.client:http. Regardlessofwhichclientyouuse,itmustdothefollowing: SubmitaPOSTrequesttowebMethodsIntegrationServer. AddresstherequesttotheURLofanservice(forexample, http://rubicon:5555/invoke/purch/postOrder). SettheContentTypeheaderfieldtotext/xml. ContainanXMLdocumentinthebodyofthemessage.Thedocumentmustbethe onlytextthatappearsinthebodyoftherequest.Donotassignittoaname=value pair. Important! WhenyousubmittheXMLdocument,placeanextracarriagereturn/new line(\r\n)attheendofittoindicatetheendoftheXMLdocument.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

369

14 Submitting and Receiving XML Documents

Example: Submitting and Receiving XML via HTTP


Thefollowingexampledescribesthevaluesthatyousetifyouusepub.client:httptoPOST anXMLdocumenttoaservice. Set this variable... url To... TheURLoftheservicethatyouwanttoinvoke.Thefollowing valuewouldinvokethe purch:postOrderservicefromaserver namedrubiconwithportnumber5555. Example http://rubicon:5555/invoke/purch/postOrder method headers.ContentType data.string OR data.bytes YouwillalsosetanyoptionalHTTPparameters,suchasauthorizationinformation,that arerequiredbyyourapplication.
post text/xml

TheXMLdocumentthatyouwanttopost.

370

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14 Submitting and Receiving XML Documents

Submitting and Receiving XML via FTP


YoucanFTPanXMLdocumenttowebMethodsIntegrationServersFTPlisteningport. (BydefaulttheFTPportisassignedtoport8021.However,thisassignmentis configurable,soyoushouldcheckwithyourwebMethodsIntegrationServer administratortoseewhichportisusedforFTPcommunicationsonyourwebMethods IntegrationServer.) WhenaclientputsafileontheIntegrationServerforthepurposeofinvokingaservice, theFTPListenerwillchooseacontenthandler,basedonthefileextension,toconvertthe filecontentintotheinputvaluesfortheservicetoinvoke.TheIntegrationServers lib/mime.typesfilecontainsthemappingoffileextensiontocontenttype. Tip! Youcaneditthemappingsinthelib/mime.typesfile(andreloaditwithout restartingIntegrationServer),byselectingSettings > Resources > Mime Typesfromthe IntegrationServerAdministratorscreen. WhentheIntegrationServerreceivesanXMLdocumentontheFTPlisteningport,it automaticallyparsesthedocumentandpassesitasanodetotheserviceinthedirectory wherethefilewasFTPed. TosubmitanXMLdocumenttowebMethodsIntegrationServerviaFTP: TheXMLdocumentcanbecontainedinafilethathaseither:

Afileextensionofxml Afileextensionwhosemimetypeisregisteredwiththeserverastext/xml. Todothis,edittheIntegrationServerslib/mime.typesfile.Forexample:


text/xml mimetype

Nofileextension Toconfigureacontenthandlertohandlefilesthathavenoextension,usethe specialkeyftp_no_extensioninthelib/mime.typesfiletoindicateanull extension.Then,specifythecontenttypemappedtoanullextension.For example,thefollowingXMLcontenthandlerisusedtohandlefileswithoutan extension:


text/xml ftp_no_extension

Ifyouwanttouseadifferentkeytospecifyanullextension,usetheproperty watt.net.ftp.noExtensionKeytospecifythekeyusedinlib/mime.typesto specifyafilewithnoextension.Thedefaultvalueofthispropertyis ftp_no_extension. Theservicetowhichyouwanttopassthedocumentmusttakeanodeasinput.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

371

14 Submitting and Receiving XML Documents

Client Requirements
IfyouwanttosubmitanXMLdocumenttoaservicethroughFTP,theapplication sendingthedocumentmustdothefollowing: 1 2 InitiateanFTPsessiononwebMethodsIntegrationServersFTPlisteningport. PointtothedirectorythatcontainstheservicetowhichyouwanttopasstheXML document. Example cd \ns\Purchasing\SubmitOrder Important! NotethattherootdirectoryforthisoperationisyourwebMethods IntegrationServersnamespacedirectory(ns),nottherootdirectoryofthetarget machine.Therefore,ifyouwanttoFTPafiletoaserviceinthePurchasingpackage, youuse\ns\Purchasing\ServiceNameasthepathtothatservice,not IntegrationServer_directory\ns\Purchasing\ServiceName. 3 CopytheXMLdocumenttothisdirectoryusingthefollowingcommand:
put XMLDoc.xml

or
put XMLDoc

WhereXMLDocisthenameofthefilethatyouwanttopasstowebMethods IntegrationServer.Thefileextensioncanbesomethingotherthanxmlifthe extensionsmimetypeisregisteredwiththeserverastext/xml.Alternatively,thefile extensioncanbeomittedifyouspecifythespecialkeyftp_no_extensioninthe lib/mime.typesfiletoindicateanullextension.SeeSubmittingandReceivingXML viaFTPonpage 371fordetails. Example put PurchaseOrder.xml NotethattheXMLdocumentyouFTPtowebMethodsIntegrationServerisnever actuallywrittentotheserversfilesystem.TheXMLdocumentyousendandthe outputfileitproduces(seebelow),arewrittentoavirtualdirectorysystem maintainedinyourISsession.

FTPing a File from a webMethods Integration Server


Thepub.clientfoldercontainsbuiltinservicesyoucanusetoFTPafilefroma webMethodsIntegrationServer.Forinformationabouttheseservices,seethewebMethods IntegrationServerBuiltInServicesReference.

372

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14 Submitting and Receiving XML Documents

Receiving XML via FTP


TheresultsfromaserviceexecutedbyanFTPrequestarewrittentothesamevirtual directorywheretheXMLdocumentwasinitiallyFTPed. Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresults(thatis,the contentsofthepipeline)areXMLencodedandreturnedasanXMLdocument. IftheservicehasanXMLoutputtemplateassignedtoit,thattemplateisappliedto theresults.(IfthetemplateisnotanXMLbasedtemplate,itisnotapplied.) Thenameoftheoutputfiletowhichresultsarewrittenis:
XMLDoc.xml.out

WhereXMLDoc.xmlisthenameoftheXMLfileinitiallyFTPedtotheservice.(Thefile extensioncanbesomethingotherthanxmliftheextensionsmimetypeisregistered withtheserverastext/xml.) YouretrievethisXMLdocumentusingtheFTPgetcommand.Forexample,ifyouput anXMLdocumentcalledPurchaseOrder.xmlonwebMethodsIntegrationServer,youwould usethefollowingFTPcommandtogetitsresults: Example get PurchaseOrder.xml.out Important! WerecommendthatyouuseauniquenameforeachXMLdocumentthat youFTPtowebMethodsIntegrationServer(perhapsbyattachingatimestamptothe name)sothatyoudonotinadvertentlyoverwriteotherFTPedXMLdocumentsor theirresultsduringanFTPsession. WhenyouendtheFTPsession,webMethodsIntegrationServerautomaticallydeletesthe originalfileanditsresultsfromyoursession.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

373

14 Submitting and Receiving XML Documents

Submitting and Receiving XML via E-mail


YoucanemailanXMLdocumenttoanemailmailboxandhavewebMethods IntegrationServerautomaticallyretrievetheemailmessageandprocesstheXML documentitcontains.Todothis,yourwebMethodsIntegrationServermustbe configuredwithanemailportthatmonitorsthemailboxtowhichtheXMLdocument willbesent.(ConsultyourwebMethodsIntegrationServeradministratortoseewhether anemailporthasbeensetuponyourwebMethodsIntegrationServer.) WhenanXMLdocumentarrivesintheemailportsmailbox,webMethodsIntegration Serverautomaticallyretrievesthemessage,parsestheattachedXMLdocument,and passestheXMLdocumentasanodetotheservicespecifiedontheemailssubjectline (or,ifaserviceisnotspecifiedonthesubjectline,theemailportsdefaultservice).

Client Requirements
TosubmitanXMLdocumenttowebMethodsIntegrationServerviaemail,yourclient programmust: PuttheXMLdocumentinanemailattachment. SettheemailsContent-Typeheadertotext/xml. SpecifythenameoftheservicethatwillprocesstheXMLdocumentintheemails subjectline.Ifyouleavethesubjectlineempty,theXMLdocumentwillbeprocessed bytheglobalserviceifoneisdefinedor,ifnot,bythedefaultserviceassignedtothe emailport(ifonehasbeenassigned).Forinformationaboutspecifyingtheports defaultservice,seeAdministeringwebMethodsIntegrationServer. TheservicethatprocessestheXMLdocumentmusttakeanodeasinput.

Example: Sending XML via E-mail


Thefollowingexampledescribesthevaluesthatyouwouldsetifyouusedpub.client:smtp toemailanXMLdocumenttoaservice.(Formoreinformationaboutusingthisservice, seethewebMethodsIntegrationServerBuiltInServicesReference.) Set this variable... to subject To... AStringspecifyingtheemailaddressthatwebMethods IntegrationServersemailportmonitors. AStringspecifyingthefullyqualifiednameoftheservice thatwebMethodsIntegrationServerpassestheattached XMLdocumentto. Example: orders:ProcessPO Ifyoudonotspecifysubject,theemailportwillinvokeits defaultservice(ifonehasbeenassignedtoit).

374

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

14 Submitting and Receiving XML Documents

Set this variable... from body

To... AStringcontainingtheemailaddresstowhichtheresults oftheservicearesent. AStringcontaininginputparametersfortheserviceinURL querystringformat.Thefollowingexamplesetsfive parameters:one,two,andthreearesettothevalues1,2and3, respectively.Theparameters$userand$passhavespecial meaningtotheemailport.Youusetheseparametersto specifytheusernameandpasswordfortheemailport.You mustspecifythesetwoparametersifauthenticationis enabledontheemailport. Example:
one=1&two=2&three=3&$user=Administrator&$pass=manage

attachments.contenttype attachments.content OR attachments.filename

AStringsetto:text/xml Thebyte[]oraStringcontainingtheXMLdocument.

AStringspecifyingthefullyqualifiednameofthefile containingtheXMLdocument.

Receiving XML via E-mail


Ifyouremailportisconfiguredtoreturnresults,theresultsfromaserviceinvoked throughtheportareemailedbacktothesenderoftheoriginalmessage,inan attachmentfilecalledxml.out. Iftheservicedoesnothaveanoutputtemplateassignedtoit,theresultsfromthe service(thatis,thecontentsofthepipeline)areXMLencodedandreturnedasan XMLdocument. Iftheservicehasanoutputtemplateassignedtoit,thattemplateisappliedtothe results. Important! Bydefault,theemailportdoesnotreturnanyresultsfromrequeststhatit receives.Ifyouwanttheporttoreturnresults,youmustexplicitlyconfigureittodo so.Forinformationaboutconfiguringtheemailporttoreturnresults,see AdministeringwebMethodsIntegrationServer.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

375

14 Submitting and Receiving XML Documents

376

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15

Subscribing to Events
378 381 387 390 391

The Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Event Handlers Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

377

15 Subscribing to Events

The Event Manager


TheEventManagermonitorstheserverforeventsandinvokeseventhandlerswhen thoseeventsoccur.AneventisaspecificactionthattheEventManagerrecognizesand aneventhandlercanreactto.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

378

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 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,successfulorunsuccessfulaccessto IntegrationServerservices,documents,andportlets,andchangesto messagingsettings.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

379

15 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. Otherpointstokeepinmindabouteventsandeventhandlers: Aneventcanhavemorethanonesubscriber,whichmeansthatasingleeventmight invokeseveraleventhandlers. Ifaneventinvokesmorethanoneeventhandler,alltheeventhandlersexecute simultaneously.Theydonotexecuteseriallyandtheyarenotinvokedinany particularorder.(Ifyouhaveaseriesofactionsthatmustexecuteinaspecific sequence,youshouldencapsulatetheentiresequencewithinasingleeventhandler.) Aneventhandlercansubscribetomorethanoneevent. Aneventhandlercanbeinvokedsynchronouslyorasynchronously.Formore information,seeInvokingEventHandlersSynchronouslyorAsynchronouslyon page 390. Wheneventhandlersrun,theydonotgenerateauditevents. Ifaneventhandlerthrowsanexception,itgeneratesanexceptionevent.Thisistrue foralleventhandlersbutexceptioneventhandlers.Whenanexceptioneventhandler throwsanexception,itdoesnotgenerateanexceptionevent.

380

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

Managing Event Subscriptions


YoucanusetheEventManagerinDevelopertomanageallofyoureventsubscriptions. TheEventManagercanperformthefollowingtasks: Subscribeeventhandlerstoevents. Vieworediteventsubscriptions. Suspendeventsubscriptions. Deleteeventsubscriptions. 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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

381

15 Subscribing to Events

To subscribe to an event on the current server 1 2 3 4 OntheToolsmenu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selecttheevent typetowhichyouwanttosubscribe. Click toaddanewsubscriber.

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 383. Comment Enabled Anoptionaldescriptivecommentaboutthissubscription. Whetherthesubscriptionisactiveorinactive.Settotruetoactivatethe subscription.Settofalsetodeactivatethesubscription.(Thisallowsyou totemporarilysuspendasubscriptionwithoutdeletingit.)

ClickOK.Subscriptionstakeeffectimmediately. Note: IntegrationServersavesinformationforeventtypesandeventsubscriptionsin theeventcfg.binfile.ThisfileisgeneratedthefirsttimeyoustarttheIntegration Serverandislocatedinthefollowingdirectory:IntegrationServer_directory\config. CopythisfilefromoneIntegrationServertoanothertoduplicateeventsubscriptions acrossservers.

382

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

Creating Event Filters


Eventfiltersallowyoutobeveryselectiveaboutwhicheventsyousubscribeto.Event filterslimittheeventsforaneventtypethatinvokeaneventhandler.Byusingevent filters,youcansubscribeaneventhandlertoonlythoseeventsgeneratedbyaparticular service,package,user,orport.Forexample,youmightwantaneventhandlertobe invokedonlywhenaspecificservicegeneratesanauditevent.Or,youmightwantan eventhandlertobeinvokedonlywhenaspecificuserlogsontotheIntegrationServer. 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:
*

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

383

15 Subscribing to Events

For this event type... GD Start Event

You create a filter for... Thefullyqualifiednameoftheservicethatisbeinginvokedusing guaranteeddelivery.Createafiltertospecifytheservicesthat, wheninvokedusingguaranteeddelivery,willinvoketheevent handler. Thefollowingpatternstringspecifiesthatallservicesthatstart withthewordsendPOandbelongtoanyfolderwillinvokethe eventhandler:
*:sendPO*

JMS Delivery Failure Event

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

N/A Thefilterforallsessionendeventsisthefollowing: *

Session End Event

N/A Thefilterforallsessionendeventsisthefollowing:
*

384

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

For this event type... Session Expire Event

You create a filter for... N/A Thefilterforallsessionexpireeventsisthefollowing:


*

Session Start Event

TheusernamefortheuserstartingthesessionontheIntegration Serverorthegroupstowhichtheuserbelongs.Createafilterto specifywhichusersorwhichusergroupsinvokeaneventhandler whentheystartasessionontheserver. Thefollowingfilterspecifiesthatasessionstarteventgenerated byauserintheAdministratorsgroupwillinvoketheevent handler.


*Administrators*

Stat Event

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* sgxorders.Auth:* sgxorders.* *.Auth*:credit*

Will select events generated by... Theservicesgxorders.Auth:creditAuth. Allservicesinthesgxorders.Auth folder,startingwiththe characterscredit. Allservicesinthesgxorders.Auth folder. Allservicesinthesgxorders folderanditssubfolders. Allservicesstartingwiththecharacterscreditthat resideinanysubfolderwhosenamestartsthe charactersAuth.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

385

15 Subscribing to Events

This filter...
*:credit* *

Will select events generated by... Allservicesstartingwiththecharacterscreditinany folder. Allservices.

Viewing and Editing Event Subscriptions


To view or edit an event subscription on the current server 1 2 3 4 5 6 OntheToolsmenu,clickEvent Manager. IntheView event subscribers forlist,selecttheeventtypeforwhichyouwanttoview subscriptions. 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.

386

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

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. ClickOKwhenyoufinishdeletingsubscriptions.Yourchangestakeeffect immediately.

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

387

15 Subscribing to Events

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. To insert services into the event handler andselectBrowse.

IntheSelectdialogbox,navigatetoandselectthepub.event:sessionStartspecification.

Stage 3

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 personwhologgedontotheIntegrationServerasamemberof theAdministratorsgroup. mailhost body Thenetworknameofyourmailhost(forexample, mail@mycompany.com).


Administrators user %userid% logged into session %sessionName% with session ID %ssnid%

Thebodyoftheemailmessagewillcontaintheusername,session name,andsessionIDforthepersonwhologgedontothe IntegrationServerasanAdministrator. 4 OntheFilemenu,clickSavetosavetheservice.

388

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

Stage 4

To test and debug the event handler

UsethetestinganddebuggingtoolsinDeveloper(suchasTestRun)totestand debugtheservice.Formoreinformationaboutthesetools,seeChapter 11,Testing andDebuggingServices.


Stage 5

To subscribe the event handler to the event

1 2 3 4

OntheTools menu,clickEvent Manager. IntheEventManagerdialogbox,intheView event subscribers forlist,selectSession Start Event. Click toaddaneweventsubscription.

IntheEnterInputValuesdialogbox,completethefollowingfields: In this field Service Filter Do this Click andusetheSelectdialogboxtonavigatetoandselectthe processLogonservice. Type: *Administrators* ThispatternstringspecifiesthattheprocessLogoneventhandlerwill executeonlywhenauserbelongingtoausergroupcontainingthe stringAdministratorslogsontotheserver. Comment Enabled Specifyadescriptivecommentaboutthissubscription. Selecttruetoactivatethesubscription.

ClickOK.Subscriptionstakeeffectimmediately.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

389

15 Subscribing to Events

Invoking Event Handlers Synchronously or Asynchronously


Bydefault,IntegrationServerinvokeseventhandlersthatsubscribetoevents synchronously.Oncetheeventhandlerisinvoked,IntegrationServerwaitsforareply beforeexecutingthenextstepintheflowservice.Thisconfigurationisusefulfor environmentsthatdonotallowtheuseofthreadorforprocessesthatrequireimmediate responses. YoucanconfigureIntegrationServertoprocesstheeventhandlersasynchronously.In thiscase,oncetheeventhandlerisinvoked,IntegrationServerexecutesthenextstepin theflowserviceimmediately.Theserverdoesnotwaitforareplybeforecontinuingthe executionoftheservice.Eachprocessrunsasaseparatethread,therebyincreasingthe performancesignificantly. Thereareserverconfigurationparametersspecifictoeacheventtypethatyoucanuseto specifywhethertheeventhandlers(services)thatsubscribetotheeventsaretobe invokedsynchronouslyorasynchronously.Theseserverconfigurationparameterswill beintheformat:watt.server.event.eventType.async. Setthevalueoftheserverconfigurationparameterspecifictotheeventtotrue,ifyou wantIntegrationServertoinvoketheeventhandlersthatsubscribetotheevent asynchronously.Setthevalueoftheserverconfigurationparameterspecifictotheevent tofalse,ifyouwantIntegrationServertoinvoketheeventhandlersthatsubscribetothe eventsynchronously.Thedefaultvalueistrue. Formoreinformationaboutspecifyingtheserverconfigurationparameters,referto AdministeringwebMethodsIntegrationServer.

390

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

Working with Events


Working with Alarm Events
AnalarmeventoccurswhenIntegrationServergeneratesamessagerelatedtothestatus oftheserver.Analarmeventcanbegeneratedforthefollowingreasons: AclientexperiencesalogonfailureorisdeniedaccesstoIntegrationServer.Aclient cannotlogonbecauseofinvalidcredentials. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

391

15 Subscribing to Events

Working with Audit Events


Anauditeventoccurswhenaservicegeneratesauditdata.Youcanusetheoptionsina servicesAuditpropertiestospecifywhenaservicegeneratesauditdata.Aservicecan generateauditdataonce,twice,orzerotimesduringexecution.Youcanuseauditevents toinvokeotherserviceswhenaparticularserviceexecutes.Forexample,youmightwant anauditeventgeneratedforacriticalservicetoinvokealoggingserviceoranotification service.Formoreinformationaboutspecifyingwhenaservicegeneratesauditdata,see ConfiguringServiceAuditingonpage 157.

Working with Exception Events


Anexceptioneventoccurswhenaservicethrowsanexception(includingwhenaflow serviceexitsonfailure).Youcanuseexceptioneventstoinvokesomeprescribed action,suchasnotifyinganadministrator,whenaparticularservicefails. Note: Keepinmindthateventhandlersareprocessedindependentlyoftheservices thatinvokethem.Eventhandlersarenotdesignedtoreplacetheerrorhandling and/orerrorrecoveryproceduresthatyouwouldnormallyincludeinyourservice. Ifanestedservicethrowsanexception,anexceptioneventisgeneratedbyeachservicein thecallstack.Forexample,ifserviceA1callsserviceB1,andB1throwsanexception, bothB1andA1generateexceptionevents(inthatorder).

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:endservice generatesaGDEndevent. EachguaranteeddeliverytransactiongeneratesaGDStarteventandaGDEndevent. YoucansubscribetoGDStartandGDEndeventstoinvokeeventhandlersthatlog guaranteeddeliverytransactionstoafileordatabase.Youmightalsowanttouse guaranteeddeliveryeventstoinvokeeventhandlersthatsendnotification.Forexample, ifyouuseguaranteeddeliverytoinvokeaservicethatprocessespurchaseorders,you mightwanttosendnotificationtoabusinessaccountmanageraboutpurchaseorders fromaparticularclient,orwhenthevalueofapurchaseorderisgreaterthanacertain amount.

392

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

393

15 Subscribing to Events

Working with JMS Delivery Failure Events


IntegrationServergeneratesaJMSdeliveryfailureeventwhenamessagewrittentothe clientsidequeuecannotbedeliveredtotheJMSprovider.Whenatransienterroroccurs, severaldeliveryattemptsmayhavebeenmade. YoumightwanttocreateaneventhandlerforaJMSdeliveryfailureeventtosend notificationorloginformationabouttheundeliveredJMSmessage.Youcanalsocreate aneventhandlerthatattemptstoresendthemessagetotheJMSprovider.

Working with JMS Retrieval Failure Events


Bydefault,IntegrationServergeneratesJMSretrievalfailureeventswhenerrorsoccur duringmessageretrievalandJMStriggerprocessing.Youcanbuildeventhandlersthat subscribetoandhandletheJMSretrievalfailureevents. AJMSretrievalfailureeventoccursinthefollowingsituations: AtriggerserviceexecutedbyaJMStriggerthrowsanontransienterrorandthe watt.server.jms.trigger.raiseEventOnExceptionpropertyissettotrue(thedefault). AtriggerserviceassociatedwithaJMStriggerendsbecauseofatransienterror,all retryattemptshavebeenmade,andtheJMStriggerisconfiguredtothrowan exceptiononretryfailure.Inaddition,the watt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(thedefault). ThemaximumdeliverycountfromtheJMSproviderhasbeenmetforthemessage andthewatt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(the default). Thewatt.server.jms.trigger.maxDeliveryCountpropertyspecifiesthemaximum numberoftimestheJMSprovidercandeliveramessagetoIntegrationServer.The defaultis100.InaJMSmessage,thepropertyJMSXDeliveryCountspecifiesthe numberoftimestheJMSproviderdeliveredthemessage.MostJMSproviderssetthis value. Whileperformingexactlyonceprocessing,theconnectiontothedocumenthistory databaseisunavailable,andtransienterrorhandlingfortheJMStriggerisconfigured to Throw exception(nontransactedJMStrigger)orRecover only (transactedJMS trigger).Inaddition,thewatt.server.jms.trigger.raiseEventOnRetryFailurepropertyis settotrue(thedefault). Whileperformingexactlyonceprocessing,thedocumentresolverserviceendswith anISRuntimeException,andtransienterrorhandlingfortheJMStriggeris configuredto Throw exception(nontransactedJMStrigger)orRecover only (transacted JMStrigger).Inaddition,thewatt.server.jms.trigger.raiseEventOnRetryFailure propertyissettotrue(thedefault). Whileperformingexactlyonceprocessing,thedocumentresolverserviceendswith anexceptionotherthananISRuntimeException.Inaddition,the watt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(thedefault).

394

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

AservicethatfunctionsasaneventhandlerforaJMSretrievalfailureeventshoulduse thepub.event:jmsReceiveErrorEventspecificationasitsservicesignature.Formore informationaboutthepub.event:jmsReceiveErrorEventspecification,seethewebMethods IntegrationServerBuiltInServicesReference.

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,seeAdministeringwebMethods IntegrationServer.

Working with Replication Events


Areplicationeventoccurswhenthepub.replicator:generateReplicationEventserviceexecutes. Youmightwanttogenerateandsubscribetoreplicationeventstoinvokeeventhandlers thatautomatethecompletionofthepackagereplicationanddistributionprocesses.For example,youcouldcreatereplicationeventhandlersthatdothefollowing: Notifypackagesubscriberswhenapackageispublished. Maintainalogofreplicatedpackages. Maintainalogofthepackagesdistributedorpushedtoyoursubscribers. Maintainalogofthepackagesyourpartnerspulledfromyou. Formoreinformationaboutthepub.replicator:generateReplicationEventservice,seethe webMethodsIntegrationServerBuiltInServicesReference.

Working with Security Events


Asecurityeventoccurswhenanadministrativeoroperationalsecurityactiontakesplace onIntegrationServerandthatsecurityactionisconfiguredforauditing. AdministrativeactionsrefertoconfigurationchangesrelatedtoIntegrationServer securityactivities.Operationalactionsrefertosuccessfulandunsuccessfulloginattempts andaccesstoIntegrationServerservices,documents,andportlets.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

395

15 Subscribing to Events

Administrativesecurityeventsinclude: Creating,modifying,anddeletingpackages,folders,andservices. Creating,deleting,ormodifyingauthenticationrelatedinformation.Thisincludes creatingnewusers,deletingusers,changingtheirsecurityattributes(forexample, passwords),settingormodifyingthemappingbetweencertificatesandusers,andso on. Creating,deleting,ormodifyingauthorizationrelatedinformation.Thisincludes creating,modifying,anddeletingACLs. Creating,deleting,ormodifyingportsettings.Thisincludesdefiningallowedor deniedactionsontheport,portmodes(allowedordeniedbydefaultinIntegration Server),andcertificatehandling. ConfiguringSSLsettingsinIntegrationServer. ModifyingorresettingOutboundPasswords. Operationalsecurityeventsinclude: SuccessfulloginstotheIntegrationServer. UnsuccessfulloginattemptstotheIntegrationServer.Theloginattemptfailurecould bebecauseofincorrectpassword,disabledaccount,SSLfailure,orexpiredcertificate. Successfulandunsuccessfulaccessestoservices,files,andpackages. Modifyingexistingpasswords. Modifyingmessagingsettings. ForinformationonconfiguringtheSecuritylogger,seewebMethodsAuditLoggingGuide. AservicethatfunctionsasaneventhandlerforaSecurityeventshouldusethe pub.event:securityspecificationasitsservicesignature.Formoreinformationaboutthe pub.event:securityservice,seethewebMethodsIntegrationServerBuiltInServicesReference.

Working with Session Events


AsessioneventoccurswhenaclientstartsorendsasessionontheIntegrationServeror whentheIntegrationServerterminatesaninactivesession.Youcansubscribetoanyof thefollowingtypesofsessionevents: Session Start eventsoccurwhenadeveloperusesDevelopertoopenasessiononthe IntegrationServerorwhenanISclientopensasessionontheservertoexecute services. Session End eventsoccurwhenadeveloperorISclientspecificallyissuesadisconnect instructiontotheIntegrationServer. Session Expire eventsoccurwhentheIntegrationServerterminatesaninactivesession. Youcansubscribetosessioneventstoinvokeeventhandlersthatmaintainyourownlog filesoreventhandlersthatsendnotificationaboutusersopeningsessionsontheserver.

396

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

15 Subscribing to Events

Working with Stat Events


AstateventoccurseachtimetheIntegrationServerupdatesthestatisticslog(stats.log). Thestatisticslogmaintainsstatisticalinformationabouttheconsumptionofsystem resources.The watt.server.stats.pollTime propertydeterminesthefrequencywithwhichthe IntegrationServerupdatesstatistics.Thedefaultfrequencyis10seconds. Youcanusestateventstoinvokeeventhandlersthatmaintainyourownlogfileorto invokeeventhandlersthatsendserverstatisticstoanetworkmonitoringsystem. Note: IntegrationServerprovidesanagentthatyoucanconfigureforusewitha networkmonitoringsystem.Forinformationaboutimplementingthisagent,seethe readmefileintheagentInstall.jarfilelocatedintheIntegrationServer_directory\lib directory.

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 393. YoucansubscribetoTxStartandTxEndeventstoinvokeeventhandlersthatlog guaranteeddeliverytransactionstoafileordatabase.Youmightalsowanttouse transactioneventstoinvokeeventhandlersthatsendnotification.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

397

15 Subscribing to Events

398

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

16

Building Services that Retry


400 400 401

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

399

16 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 151. 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().

400

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

16 Building Services that Retry

Adapter Services and Retry Behavior


AdapterservicesbuiltonIntegrationServer6.0orlater,andbasedontheART framework,detectandpropagateexceptionsthatsignalaretryifatransienterroris detectedontheirbackendresource.Atruntime,adapterservicesdetectiftheirbackend serverisdownorthenetworkconnectionisbroken.Theadapterservicepropagatesan exceptionthatisbasedonISRuntimeException.Thisbehaviorallowsfortheautomatic retrywhentheserviceisinvokedbyatriggerorinvokedwithinaflowthatisconfigured toretrywhenanISRuntimeExceptionoccurs. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

401

16 Building Services that Retry

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. 2 Insert an inner SEQUENCE step for the try sequence. Thissequencewillcontainthelogic thatyouwanttheservicetoperform. SetthisinnertrysequencetoexitonFAILURE.Thisindicatesthatthetrysequence willexitwhenastepintheSEQUENCEfails.TheIntegrationServerwillthenexecute thenextstepintheflowservice,whichisthecatchsequence. Makesurethatthetrysequenceisachildoftheoutersequencethatyouinsertedin step 1. 3 Insert the logic that you want the service to perform.Thesestepscontaintheworkthatyou wanttheservicetodo. Makesuretoindentthestepsbelow/underthetrySEQUENCEstep. 4 Insert a SEQUENCE step for the catch sequence.Thissequencecontainsthestepsneeded tocatchtheexception,determineitscause,andthendeterminewhethertheservice canberetried. SetthecatchsequencetoexitwhenDONE.ThisindicatesthattheIntegrationServer executeseverystepinthecatchsequence,evenifoneofthestepsfails. Makesurethatthecatchsequenceisachildoftheoutersequencethatyouinsertedin step 1. 5 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.

402

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

16 Building Services that Retry

Insert error evaluation logic. Thislogicshoulddothefollowing:

Determinewhetherthelasterrorisatransienterrorthatcanberetried. Note: Iftheflowserviceincludesanadapterservice,andatransienterror occursduringadapterserviceexecution,theadapterservicethrowsan exceptionthatextendstheISRuntimeException.

Iftheservicecanberetried,setaflagtoindicatethis.Forexample,youmightseta variablenamedisTransientErrortotrue.AsubsequentBRANCHstepwilluse theflagtodeterminewhethertoexecutethepub.flow:throwExceptionForRetryService.

Keepinmindthatyoumightneedtousemorethanoneservicetohandletheerror, determineifitwascausedbyatransienterror,andsetthetransienterrorflag. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

403

16 Building Services that Retry

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.

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

404

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

16 Building Services that 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. 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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

405

16 Building Services that Retry

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

1.2.3

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.

406

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

webMethods Flow Steps


408 410 412 413 414 415 418

BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

407

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 Name1 if the value of choice is Name2 Name1 Name2

Name of the switch field is choice

if the value of choice is NameN if choice does not exist or has a value of $null if the value of choice is an empty string Otherwise

NameN $null no label $default

Branching on Expressions
Whenyoubranchonexpressions,yousettheEvaluate labelspropertyoftheBRANCH steptotrue.IntheLabelpropertyforeachchildstep,youwriteanexpressionthat includesoneormorevariables.Atruntime,theBRANCHstepexecutesthefirstchild stepwithanexpressionthatevaluatestotrue. Ifyouwanttospecifyachildsteptoexecutewhennoneoftheexpressionsaretrue,set thelabelofthechildstepto$default.

408

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

A webMethods Flow Steps

BRANCH step using expressions


if the expression of first child is true if the expression of second child is true Child1 Child2

Evaluate labels is set to true if the expression of nth child is true Otherwise

ChildN $default

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

409

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.

410

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

411

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.

412

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

413

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.

414

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

REPEAT
TheREPEATsteprepeatedlyexecutesitschildstepsuptoamaximumnumberoftimes thatyouspecify.ItdetermineswhethertoreexecutethechildstepsbasedonaRepeat on condition.Youcansettherepeatconditiontooneofthefollowing: Repeatifanyoneofthechildstepsfails. Repeatifalloftheelementssucceed. YoucanalsospecifyatimeperiodthatyouwanttheREPEATflowsteptowaitbeforeit reexecutesitschildsteps.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

415

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

416

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.UseinaWebautomationservicewhenyou wanttorepeataloadandquerystepandaNextPagebuttonexistsinthecurrent document,indicatingthatthereareadditionalpagestobeprocessed.Endthe REPEATflowstepwhenthequerystepfailstoretrieveaNextPagebuttoninthe currentdocument.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

417

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 not met... child If exit condition is not met... 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

418

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

419

A webMethods Flow Steps

420

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Regular Expressions
422 422 422

What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

421

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.

422

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

423

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.

424

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

425

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.

426

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

427

B Regular Expressions

428

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Supported Data Types


430 433

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

429

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.

430

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.Forinformationabout applyingconstraintstovariables,seeApplyingConstraintstoVariableson page 273.

Java Classes for Objects


YoucanfurtherdescribethecontentsofanObjectorObjectlistvariablebyapplyinga Javaclasstothevariable.WhenyouapplyasupportedJavaclasstoanObjectorObject listvariable,Developerchangestheiconforthevariable.ApplyingJavaclassestoObjects andObjectlistscanprovidethefollowingbenefits: Otherdeveloperscaneasilyseethetypesyourserviceexpectsasinputsandproduces asoutput. OtherdeveloperscaneasilyseethetypescontainedinanISdocumenttype. Youcaninputvaluesforthevariablewhentestinganddebugging. YoucanassignvaluestovariablesinthepipelineusingtheSet Value modifier.

Note: WhenyouinputvaluesforaconstrainedObjectduringtestingorwhen assigningavalueinthepipeline,Developervalidatesthedatatomakesureitisofthe correcttype.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

431

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[]

432

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

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,Document,andObject.Arrayvariablesarethosethathold multiplevalues,suchasStringlist,Stringtable,documentlist,andObjectlist.For example,youcanlinkaStringtothesecondelementofaStringlist. Ifyoudonotspecifywhichelementinthearrayvariablethatyouwanttolinktoorfrom, DeveloperusesthedefaultrulesonthePipelinetabtodeterminethevalueofthetarget variable.Thefollowingtableidentifiesthedefaultpipelinerulesforlinkingtoandfrom arrayvariables.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

433

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]

434

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

435

C Supported Data Types

Asourcevariablethatisthechildofadocumentlististreatedlikeanarraybecausethere isonevalueofthesourcevariableforeachdocumentinthedocumentlist.Forexample: If you link... DocumentList1 String1 To... StringList1

Where the value of DocumentList1 is... DocumentList1 DocumentList1 [0] a DocumentList1 [1] String1 b DocumentList1 [2] String1 c String1

Then the value of StringList1 is StringList1 a b c

436

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Conditional Expressions
438 439 442 448 449 452

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

437

D Conditional Expressions

Overview
webMethodsIntegrationServerprovidessyntaxandoperatorsthatyoucanusetocreate expressionsforusewiththeBRANCHstep,pipelinemapping,andtriggers. InaBRANCHstep,youcanuseanexpressiontodeterminethechildstepthat webMethodsIntegrationServerexecutes.Atruntime,theIntegrationServerexecutes thefirstchildstepwhoseconditionalexpressionevaluatestotrue.Formore informationabouttheBRANCHstep,seeTheBRANCHSteponpage 176 Inpipelinemapping,youcanplaceaconditiononthelinkbetweenvariables.Atrun time,webMethodsIntegrationServeronlyexecutesthelinkiftheassignedcondition evaluatestotrue.Formoreinformationaboutapplyingconditionstolinksbetween variables,seeApplyingConditionstoLinksBetweenVariablesonpage 219. 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 452.

438

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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


price %address/postalCode%

Explanation Valueoftheprice variable ValueofthepostalCode variableintheaddress document Valueofthefirst elementinthepoItems array

%poItems[0]%

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

439

D Conditional Expressions

Value Type String

Syntax string OR string

Description Literalstring.Usethisvaluetypetocomparethe valueofavariabletoastring.

Example
Favorite Customer Favorite Customer

Explanation Valueistheliteralstring FavoriteCustomer Valueistheliteralstring FavoriteCustomer

Note: Stringsnotenclosedinquotes(or)are interpretedasvariablenames. Number number Number.Thefollowingexamplesindicatethe acceptednumberformats: Examples


-10, 5, 100 5.0, 6.02 6.345e+4

Explanation Integers Floatingpointnumber (java.lang.Double) Scientificnotation

Null

$null

Variableisnullormissing.Typicallycompared withavariablenametodetermineifthevariable isnullormissingfromtheinputdata. Example


%quantity% = $null

Explanation Evaluatestotrueifthe quantityvariableis missingfromtheinput dataorisnull

440

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

441

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 !color & !size

Evaluates to true if... Thequantityvariabledoesnot existorisnull. Thecolorvariabledoesnotexistor isnullandthesizevariabledoes notexistorisnull.

Operators
Expressionscanincluderelationalandlogicaloperators.Relationaloperatorsareusedto comparevaluestoeachother.Logicaloperatorsareusedtocombinemultipleexpressions intoasinglecondition.

Relational Operators
Youcanuserelationaloperatorstocomparethevalueoftwofieldsoryoucancompare thevalueofafieldwithaconstant.TheIntegrationServerprovidestwotypesof relationaloperators:standardandlexical. Standardrelationaloperatorscanbeusedinexpressionsandfilterstocomparethe contentsoffields(variables)withothervariablesorconstants. Lexicalrelationaloperatorscanbeusedtocomparethecontentsoffields(variables) withstringvaluesinBroker/localtriggerfilters. Relationaloperatorsaresometimescalledcomparisonoperators.

442

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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). IfyouuseastandardrelationaloperatortocomparenumbersinfieldsoftypeString, IntegrationServertreatsthecontentsinthefieldasnumbers.TostopIntegration Serverfromtreatingthevalueasanumber,youcanputquotes(or)aroundthe variablenameintheexpression.Forexample%var1%=%var2%. 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"

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

443

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"

444

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

D Conditional Expressions

Operator <=

Syntax a<=b

Description Lessthanorequalto. This example...


unitPrice <= 100 companyID <= "Acme"

Evaluates to true if.. ThevalueoftheunitPricevariable islessthanorequalto100. ThevalueofthecompanyID variableislessthanorequalto 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. IfyouusealexicaloperatortocomparenumbersinfieldsoftypeString,Integration Servertreatsthenumbersasstrings. Filtersthatuselexicalrelationaloperatorstocomparestringvalueswillbesavedwith thetriggersubscriptionontheBroker.Filtersthatusestandardrelationaloperatorsto comparestringvalueswillnotbesavedontheBroker. WhenyouviewfiltersontheBrokeruserinterface,alexicaloperatorappearsasits equivalentstandardoperator.Forexample,theexpression%myString% L_EQUALS "abc"appearsasmyString=="abc".

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

445

D Conditional Expressions

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

446

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

447

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

448

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

449

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

Addressing Variables that Contain Special Characters


Ifavariablenamecontainsanyofthespecialcharacterslistedinbelow,youneedtouse thefollowingnotationtoaddressthevariable: Enclosethepathtothevariableandthevariablenamein%(percentsymbols). Enclosethevariablenamethatcontainsspecialcharactersin(quotationmarks).

450

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

451

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.

452

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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" %price% L_LESS_THAN 50 "stringName" > 12 myBoolean <= "true"

Nocomparisonoperators Astandardrelationaloperatorto comparefieldsoftypeString Alexicalrelationaloperatortocompare fieldsthatarenotoftypeString AfieldoftypeStringcomparedwitha numericvalue Operatorsotherthan=,==,!=,or<>to compareanObjectconstrainedasa Booleanwithavalue AnObjectconstrainedasaBoolean comparedwithafieldoftypeString

myBoolean = "stringFieldName"

Note: ExpressionsthatcheckanObject constrainedasaBooleanforatrueorfalse valueshouldincludetrueorfalseas partofthefilter.Thestringconstantinthe expression(trueorfalse)iscase insensitive.


%fieldName% = $null fieldName = /^(a|b)\1$/

A$nulltoken Regularexpressionsthatcontainback references Regularexpressionsthatusequantifiers otherthan+,?,and* Regularexpressionsthatuseextended metacharacters

/a{1}/ /a{1,5}/
fieldName = /\w/

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

453

D Conditional Expressions

454

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

jcode tags
456 456

jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

455

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

456

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

457

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

458

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

459

E jcode tags

460

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Validation Content Constraints


462 463 473

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

461

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

462

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

F Validation Content Constraints

Content Types
ThefollowingtableidentifiesthecontenttypesyoucanapplytoString,Stringlist,or Stringtablevariables.Eachofthesecontenttypescorrespondstoabuiltinsimpletype definedinthespecificationXMLSchemaPart2:Datatypes. Note: FordetailsaboutconstraintsforObjectsandObjectlists,seeAppendix C, SupportedDataTypes. 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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

463

F Validation Content Constraints

Content Types date

Description 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)

dateTime

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

464

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

F Validation Content Constraints

Content Types double

Description Doubleprecision64bitfloatingpointtype. Constraining Facets enumeration,maxExclusive,maxInclusive,minExclusive, minInclusive,pattern Example


6.02E23, 3.14, -26, 1.25e-2

duration

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

465

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

466

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

467

F Validation Content Constraints

Content Types IDREF

Description AreferencetoanelementwithauniqueID.ThevalueofIDREFis thesameastheIDvalue.TheIDREFdatatyperepresentsthe IDREFattributetypefromtheXML1.0Recommendation. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

IDREFS

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

468

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

F Validation Content Constraints

Content Types long

Description 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

negativeInteger

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

469

F Validation Content Constraints

Content Types nonNegativeInteger

Description 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

positiveInteger

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

470

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

F Validation Content Constraints

Content Types string

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

token

Representstokenizedstrings.Setofstringsthatdonotcontainthe carriagereturn(#xD),linefeed(#xA),ortab(#x9)characters, leadingortrailingspaces(#x20),orsequencesoftwoormore spaces. Constraining Facets enumeration,length,maxLength,minLength,pattern,whiteSpace

unsignedByte

Awholenumbergreaterthanorequalto0,butlessthanorequal to255. Constraining Facets enumeration,fractionDigits,maxExclusive,maxInclusive, minExclusive,minInclusive,pattern,totalDigits Example


0, 112, 200

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

471

F Validation Content Constraints

Content Types unsignedInt

Description 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

472

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

473

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: Nowhitespace normalizationisperformed.

Usage Notes minExclusivemustbelessthan orequaltomaxExclusive. Youcannotspecify minInclusiveandminExclusive forthesamecontenttype. minInclusivemustbelessthan orequaltomaxInclusive. Youcannotspecify minInclusiveandminExclusive forthesamecontenttype. minLengthmustbelessthanor equaltomaxLength.

minInclusive

minLength pattern

totalDigits

totalDigitsmustbegreater thanorequaltofractionDigits.

whiteSpace

Carriagereturns(#xD), linefeeds(#xA),andtabs(#x9)are replacedwithasinglespace (#x20). Afterthewhitespace normalizationspecifiedbyreplace isperformed,sequencesofspaces (#x20)andleadingandtrailing spaces(#x20)areremoved.


collapse:

replace:

474

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

475

F Validation Content Constraints

476

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Validation Errors and Exceptions


478 478 492 497

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

477

G Validation Errors and Exceptions

Overview
Thisappendixdescribesthefollowing: Validationerrors Validationexceptions ErrorsandwarningsthatmayoccurwhilegeneratinganISschema

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.

478

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

479

G Validation Errors and Exceptions

Error Code DT013

Message and Description [ISC.0082.9474] The input has invalid characters. Cause: ThespecifiedwhiteSpacevalueisinvalid.The valueofthewhiteSpacefieldcanbepreserve,replace,or collapse.

DTBinary001

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

DTDecimal001

[ISC.0082.9293] No matching choice value Cause: Thedecimalvalueisnotanelementlistedinthe choicesfield.

DTDecimal002

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsabledecimal.

DTDecimal003

[ISC.0082.9294] Value is less than minimum Cause: Thedecimalvalueislessthanthevaluespecified intheminimum exclusiveorminimum inclusivefield.

480

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

G Validation Errors and Exceptions

Error Code DTDecimal004

Message and Description [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.

DTDouble001

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

DTFloat001

[ISC.0082.9293] No matching choice value Cause: Thefloatvalueisnotanelementlistedinthe choicesfield.

DTFloat002

[ISC.0082.9294] Value is less than minimum Cause: Thefloatvalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

481

G Validation Errors and Exceptions

Error Code DTFloat003

Message and Description [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.

DTInt001

[ISC.0082.9293] No matching choice value Cause: Theintegervalueisnotanelementlistedinthe choicesfield.

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.

DTInt004

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsableinteger.

DTINTEGER001

[ISC.0082.9293] No matching choice value Cause: Theintegervalueisnotanelementlistedinthe choicesfield.

DTINTEGER002

[ISC.0082.9246] Value does not conform to datatype Cause: Thevalueisnotaparsableinteger.

DTINTEGER003

[ISC.0082.9294] Value is less than minimum Cause: Theintegervalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

DTINTEGER004

[ISC.0082.9295] Value is greater than maximum Cause: Theintegervalueisgreaterthanthevalue specifiedinthemaximum exclusiveormaximum inclusive field.

482

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

G Validation Errors and Exceptions

Error Code DTLong001

Message and Description [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.

DTList001

[ISC.0082.9293] No matching choice value Cause: Thesequenceofvaluesinthelistisnotanelement inthechoicesfield.

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.

DTList004

[ISC.0082.9299] Datatype definition is missing Cause: Datatypeorsimpletypedefinitionisnotfound.It ispossiblethatadependentISschemathatcontainsthis datatypedefinitionwasremovedfromtheISNamespace.

DTRecurringDuration001

[ISC.0082.9293] No matching choice value Cause: Therecurringdurationvalueisnotanelement listedinthechoicesfield.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

483

G Validation Errors and Exceptions

Error Code DTRecurringDuration002

Message and Description [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.

DTTime002

[ISC.0082.9294] Value is less than minimum Cause: Thetimevalueislessthanthevaluespecifiedin theminimum exclusiveorminimum inclusivefield.

484

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

G Validation Errors and Exceptions

Error Code DTTime003

Message and Description [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.

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

485

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.

486

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

G Validation Errors and Exceptions

Error Code NV006

Message and Description [ISC.0082.9006] Unable to locate a matching attribute declaration Cause: Thiselementcarriesanattributethatisnot declaredintheelementdeclarationintheISschema. Response: Checktomakesurethatthedocumentonly useselementattributesthataredeclaredintheschema.

NV007

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

487

G Validation Errors and Exceptions

Error Code NV010

Message and Description [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.

NV011

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

488

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0