8-0-SP1 Developer Users Guide

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
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
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
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
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
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
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
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
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
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
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
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
15
Table of Contents
16
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
{} |
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
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
19
About This Guide
20
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
23
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
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.
25
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
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.
27
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
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.
29
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
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.
31
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
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.
33
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
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.
35
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
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.
37
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
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.
39
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
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
41
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
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
45
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
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.
47
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
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.
49
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
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.
51
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
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.
53
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
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.
55
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
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.
57
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
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.
59
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
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.
61
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
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.
63
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
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.
65
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
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
67
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
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.
69
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
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.
71
72
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 .
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
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
75
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
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.
77
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
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.
79
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
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.
81
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
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.
83
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
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
85
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
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.
87
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
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.
89
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
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.
91
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
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.
93
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
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.
95
96
Locking and Unlocking Elements

98 100 104 109 111
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
99
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
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.
101
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
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
103
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
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.
105
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
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
107
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
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.
109
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
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.
111
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
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
115
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
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.
117
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
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.)
119
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
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.
121
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
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.
123
124
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
127
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
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).
129
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
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.
131
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
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.
133
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
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.
135
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
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.
137
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
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.
139
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
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.
141
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
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.
143
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
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:
145
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
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
147
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
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.
149
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
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.
151
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
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.
153
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
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.
155
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
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.
157
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
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.
159
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
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.
161
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
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.
163
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
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
165
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
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
169
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
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...
171
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
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.
173
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
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.
175
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
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.
177
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
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).
179
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
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.
181
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
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.
183
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
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.
185
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
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.
187
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
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.
189
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
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
191
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
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.
193
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
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.
195
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
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
UsethePipelinetabtolinktheelementsoftheinputarraytotheinputvariables requiredbyeachchildoftheLOOPstep.Formoreinformationaboutusingthe Pipelinetab,seeChapter 8,MappingDatainaFlowService. Important! WhenyoubuildaLOOPstep,makesurethatyouspecifytheoutputarray variableintheLOOPOutput arraypropertybeforecreatingalinktotheoutputarray variablewithinaMAPorINVOKEstepinthebodyoftheLOOP.Ifyouspecifythe outputarrayvariableaftercreatingalinktoit,thelinkwillfailatruntime.Youcan testthestepinDevelopertoseeifthelinksucceeds.Ifthelinkfails,deletethelinkto theoutputarrayvariableandthenrecreateit.
197
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
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.
199
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
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
203
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
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.
205
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
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.
207
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
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.
209
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
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.
211
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
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.
213
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
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
215
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
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.
217
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
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
219
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
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).
221
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
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[].
223
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
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.
225
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
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.
227
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
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.
229
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
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.
231
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
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.
233
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
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.
235
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
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.
237
238
Creating IS Schemas, IS Document Types, and Specifications

240 250 267
Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an IS Document Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
241
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
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.
243
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
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.
245
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
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.
247
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
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.
249
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
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.
251
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
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.
253
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
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
255
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
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.
257
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
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.
259
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
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.
261
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
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.
263
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
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
265
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
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.
267
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
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.
269
270
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
273
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
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.
275
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
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.
277
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
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.
279
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
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.
281
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
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);
283
// 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
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.
285
286
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
289
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
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.
291
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
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.
293
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
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.
295
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
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.
297
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
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.
299
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
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.
301
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
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.
303
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
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.
305
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
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.
307
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
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.
309
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
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.
311
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
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.
313
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
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.
315
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
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.
317
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
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.
319
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
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.
321
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
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.
323
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
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
327
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
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.
329
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
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.
331
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
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
333
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
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
335
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
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
337
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
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}.
339
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
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
341
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
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.
343
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
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.
345
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
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.
347
348
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
351
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
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.
353
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.

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

ThissectiondescribesthefilesthatDevelopergeneratesforaVisualBasicclient application.
General Files
File Name ServiceName.vbp ServiceNameReadme.txt Description TheVisualBasicprojectfile. Thefilethatcontainsinformationandinstructionsforthe VisualBasicclientcode.Refertothisfileforinformation aboutdeployingyourVisualBasicclientapplication.
356
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.
357
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
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

ThissectiondescribesthefilesthatDevelopergeneratesforanExcelclientapplication. File Name ServiceNameReadMe.txt Description Afilethatcontainsinformationandinstructionsforthe VisualBasicclientcode.Refertothisfileforinformation aboutdeployingyourVisualBasicclientapplication. Anexamplefilethatillustrateshowtousetheserviceclass inaspreadsheet.Thismoduleisdependentonobjectsin theprojecttemplatethatDeveloperprovides.Itisnot intendedforuseasisincustomapplications. Theserviceobject.Youincludethisobjectintoyourown project.
ServiceName.bas
ServiceName.cls
359
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
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.
361
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
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
363
Output from the Service

Bydefault,webMethodsIntegrationServerdisplaystheoutputfromaserviceinaHTML Webpage,usingatabletorendertheoutputvalues.However,youcanformattheoutput usingoutputtemplates.Youcanuseanoutputtemplatethatformatstheoutputfromone serviceandincludesaURLthatinvokesanotherservice.Formoreinformationabout outputtemplates,seeAssigninganOutputTemplatetoaServiceonpage 138.
364
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
367
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
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.
369
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
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.
371
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
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.
373
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
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.
375
376
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
379
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
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
381
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
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:
*
383
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
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.
385
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
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
387
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
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.
389
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
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.
391
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
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.
393
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
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.
395
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
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.
397
398
16
Building Services that Retry

400 400 401
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
401
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
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.
403
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
# 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.
405
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
webMethods Flow Steps

408 410 412 413 414 415 418
BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
409
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
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.
411
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
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
413
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
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.
415
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
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.
417
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
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.
419
420
Regular Expressions
422 422 422
What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
423
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
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.
425
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
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.
427
428
Supported Data Types

430 433
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Pipeline Rules for Linking to and from Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
431
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
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.
433
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
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
435
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
Conditional Expressions
438 439 442 448 449 452
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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]%
439
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
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
441
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
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"
443
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
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".
445
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
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
447
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
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.
449
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
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 \\
451
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
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/
453
454
jcode tags
456 456
jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
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
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>> --}
459
E jcode tags
460
Validation Content Constraints

462 463 473
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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
463
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
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
465
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
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
467
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
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
469
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
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
471
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
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
473
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
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.
475
476
Validation Errors and Exceptions

478 478 492 497
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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
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.
479
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
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.
481
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
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.
483
Error Code DTRecurringDuration002
Message and Description [ISC.0082.9294] Value is less than minimum Cause: Therecurringdurationvalueislessthanthevalue specifiedintheminimum exclusiveorminimum inclusive field.
[ISC.0082.9295] Value is greater than maximum Cause: Therecurringdurationvalueisgreaterthanthe valuespecifiedinthemaximum exclusiveormaximum inclusivefield.
[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
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.
485
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
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.
487
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
Error Code NV014
Message and Description [ISC.0082.9017] typeName is not validly derived from declaredTypeName Cause: Thiserroroccurswhenthefirsttypeisusedina contextwherethesecondtypeisexpected,andeitherthe firsttypeisnotthesameasthesecondtypeorthefirst typeisnotvalidlyderivedfromthesecondtype. Response: Checktomakesurethatthecorrecttypesare specifiedintheschemaandthatthecorrect correspondingtypesareusedinthedocument.
NV015
[ISC.0082.9018] typeName is an abstract type and cannot be used directly to validate content Cause: Thespecifiedtypeisanabstracttypethathasbeen eitherdeclaredornominated.Abstracttypescannotbe usedtovalidateelementcontent. Response: Makesuretouseonlyconcretetypeswhen validatingelementcontent.
NV016
[ISC.0082.9019] elementName is an abstract element and cannot appear in an instance Cause: Theelementdeclarationidentifiestheelementas anabstractelement.Abstractelementscannotappearin instancedocuments. Response: Makesuretoonlyuseconcreteelementsin instancedocuments.
NV017
[ISC.0082.9020] QName - xsi:type is used incorrectly (declared type is anonymous) Cause: Atypeisnominatedusingxsi:typeforanelement whosedeclarationcontainsananonymoustype.Anew typecannotbederivedfromananonymoustypebecause newtypescanbederivedonlyfromnamedtypes. Response: Besuretouseonlynamedtypeswhen declaringnewtypes.
489
Error Code NV018
Message and Description [ISC.0082.9021] Contains invalid text Cause: Theschemaprocessorencounteredaninvalid pieceoftext.Itispossiblethattheinstancedocument containsasimpletypewhereelementdeclarationsare interspersedwithtext.Simpletypescannotcontain elementdeclarations. Response: Checktomakesurethatthedocument conformstotheschema.
VV001
[ISC.0082.9025] Missing Object Cause: Arequireddocument(IDataobject)orvariableis missingfromtheinput. Response: Besurethattheargumentsarebeingpassed properlytothevalidator.
VV002
[ISC.0082.9026]UndefinedObjectfound Cause: Adocument(IDataobject)containsanorphan variable.(ThismessageonlyappearsiftheAllow unspecified fieldspropertyintheConstraintscategoryofthe PropertiespanelisFalse.) Response: Makesurethatallvariablesaredefined,or checktheboxtoallowunspecifiedfieldsonthe constraintstaboftheVariablePropertiesdialogbox.
VV003
[ISC.0082.9027] Dimension mismatch, List expected Cause: Thevaluebeingvalidatedisascalarvalueora multidimensionalarray(Stringtable),howeverthe variableitisbeingvalidatedagainstisalist(one dimensionalarray). Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9028] Dimension mismatch, Single item expected Cause: Thevaluebeingvalidatedisanarrayvalue(alist oratable).Thevariableitisbeingvalidatedagainstis scalar. Response: Checktomakesurethatthedocument conformstotheschema.
490
Error Code
Message and Description [ISC.0082.9029] Dimension mismatch, Table expected Cause: Thevaluebeingvalidatedisascalarvalueoraone dimensionalarray(list).Thevariableitisbeingvalidated againstisatwodimensionalarray(table). Response: Checktomakesurethatthedocument conformstotheschema.
VV004
[ISC.0082.9030] Type mismatch, String expected Cause: ThevalueisbeingvalidatedagainstaString variable,buttheISdatatypeofthevalueisnotaString. Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9031] Type mismatch, Document expected Cause: ThevalueisbeingvalidatedagainstanIS documenttypevariable,buttheISdatatypeofthevalue isnotanISdocumenttype. Response: Checktomakesurethatthedocument conformstotheschema. [ISC.0082.9032] Type mismatch, Object expected Cause: ThevalueisbeingvalidatedagainstanObject variable,buttheISdatatypeofthevalueisnotanObject. Response: Checktomakesurethatthedocument conformstotheschema.
491
Validation Exceptions
Atruntime,theserviceperformingvalidationeithersucceedsorfails.Iftheservicefails, webMethodsIntegrationServerthrowsavalidationexception.Avalidationexceptionis generatedifoneofthefollowingistrue: Errorsaredetectedintheobject(XMLnode,pipeline,ordocument(IDataobject)) thatispassed(forexample,nullvalue). Thebasicvalidationcontractisviolated(forexample,abinarytreeispassedinstead ofadocument(IDataobject)asexpected). Youspecifythattheserviceshouldfailiftheobjecttobevalidated(XMLnode, pipeline,ordocument(IDataobject))didnotconformtotheISschemaorIS documenttype(forexample,failIfInvalid=true).Ifthisisthereasonfortheexception, webMethodsIntegrationServerinsertsthevalidationerrorsintotheexception message. Thefollowingtableidentifiesanddescribesthevalidationexceptionsthatcanbe generated. Default Exception Message [ISS.0062.9021] object is null When is it thrown? Realtimeand designtime Description Cause: Theobjecttobevalidateddoes notexistinthepipeline. Response: LinkanXMLnodeor documentvariabletotheobject variableinService In. [ISS.0062.9022] %NSName% object does not exists Realtimeand designtime Cause: TheISdocumenttypeorIS schemaspecifiedfortheconformsTo variabledoesnotexistintheIS Namespace. Response: Changethevalueof conformsTotobeanISdocumenttype orISschemathatexistsintheIS namespace. [ISS.0062.9024] webMethods Integration Server does not support this type of validation (may or may not support in the future) Realtimeand designtime Cause: Theobjecttobevalidatedis notoneofthetypessupportedby validation. Response: Currently,onlyXML, pipeline,anddocument(IDataobject) validationissupported.
492
Default Exception Message [ISS.0062.9202] Invalid: minLength
When is it thrown? Designtime
Description Cause: Themin lengthiseithernota parsablenumberorconflictswithmax length. Response: Changethemin lengthvalue andmakesurethatitiswithinthe allowedrangeforthecontenttype.
[ISS.0062.9203] Invalid: maxLength
Designtime
Cause: Themax lengthiseithernota parsablenumberorconflictswith minimumlength. Response: Changethemax lengthvalue andmakesurethatitiswithinthe allowedrangeforthecontenttype.
[ISS.0062.9211] Invalid Regular Expression: Expression
Designtime
Cause: ThepatternisaninvalidPerl regularexpression. Response: Modifythepatternand makesurethatitisPerlregular expression.
[ISS.0062.9212] Invalid: minInclusive
Designtime
Cause: ThespecifiedminInclusivevalue isinvalid.Forexample,the minInclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesuretheminInclusive isavalidnumberforthespecified contenttype.
[ISS.0062.9213] Invalid: minExclusive
Designtime
Cause: ThespecifiedminExclusive valueisinvalid.Forexample,the minExclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesuretheminExclusive isavalidnumberforthespecified contenttype.
493
Default Exception Message [ISS.0062.9214] Invalid: maxInclusive
Description Cause: ThespecifiedmaxInclusive valueisinvalid.Forexample,the maxInclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesurethemaxInclusive isavalidnumberforthespecified contenttype.
[ISS.0062.9215] Invalid: maxExclusive
Designtime
Cause: ThespecifiedmaxExclusive valueisinvalid.Forexample,the maxExclusivevalueforavariablewith contenttypeconstraintofshortmust alsobeashort. Response: MakesurethemaxExclusive isavalidnumberforthespecified contenttype.
[ISS.0062.9230] Invalid scale
Designtime
Cause: Thevalueofaconstraining facethasaninvalidscale. Response: Examinetheconstraining facetvaluestomakesurethevalues donotconflict.
[ISS.0062.9231] Exceeds precision: minInclusive
Designtime
Cause: ThevalueoftheminInclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof minInclusiveortotalDigitstomakesure thevaluesdonotconflict.
[ISS.0062.9232] Exceeds precision: minExclusive
Designtime
Cause: ThevalueoftheminExclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof minExclusiveortotalDigitstomakesure thevaluesdonotconflict.
[ISS.0062.9233] Exceeds precision: maxInclusive
Designtime
Cause: ThevalueofthemaxInclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof maxInclusiveortotalDigitstomakesure thevaluesdonotconflict.
494
Default Exception Message [ISS.0062.9234] Exceeds precision: maxExclusive
Description Cause: ThevalueofthemaxExclusive constrainingfacetexceedsthevalue specifiedfortotalDigits. Response: Changethevalueof maxExclusiveortotalDigitstomakesure thevaluesdonotconflict.
[ISS.0062.9235] Invalid enumerated item
Designtime
Cause: Acontenttypeconstraintis definedintermsofthecollectiveset ofconstrainingfacetvalues.Together, thesevaluesdeterminetheallowed valuesandpropertiesofthecontent type.Theconstrainingfacetvalueyou justspecifiedmayconflictwithother constrainingfacetvalues.For example,ifyouspecifylengthforthe stringcontenttype,youcannot specifymin lengthormax length. Response: Examinetheconstraining facetvaluestomakesurethevalues donotconflictwitheachother.
[ISS.0062.9302] Maximum is less than minimum
Designtime
Cause: Invalidcondition.The maximumvalueislessthanthe minimumvalue. (maximum<minimum) Response: Changethemaximumor minimumvaluetoeliminatethe conflict.
495
Default Exception Message [ISS.0062.9303] Minimum is out of range (Valid range is from lowerBound to upperBound)
Description Cause: Theminimumvalueisoutof thevalidrangeforthecontenttype. Response: Changetheminimumvalue (min exclusive,min inclusive,ormin length)andmakesurethatitiswithin theallowedrangeforthecontent type.
[ISS.0062.9304] Maximum is out of range (Valid range is from lowerBound to upperBound)
Designtime
Cause: Thespecifiedmaximumvalue isoutofthevalidrangeforthe contenttype. Response: Changethemaximum value(max exclusive,max inclusiveor max length)andmakesurethatitis withintheallowedrangeforthe contenttype.
496
IS Schema Generation Errors and Warnings

WhenyoucreateanISschemafromaDTDoranXMLSchemadefinition,youmay receiveerrorsorwarnings.Thefollowingtableidentifiesanddescribestheerrorsyou mightreceivewhencreatinganISschema.ErrororwarningcodesthatbeginwithDTDC areerrorsthatoccurwhenyougenerateanISschemafromaDTD(orfromanXML documentthatreferencesanexistingDTD).Errororwarningcodesthatbeginwith XSDCareerrorsthatoccurwhenyougenerateanISschemafromanXMLSchema definition. Note: YoumightalsoreceivetheseerrorsandwarningswhenyougenerateanIS documenttypeorflowservicefromanXMLSchemadefinition,DTD,orXML documentthatreferencesaDTD.FormoreinformationaboutcreatinganIS documenttype,seeCreatinganISDocumentTypeonpage 250.Formore informationaboutcreatingaflowservice,seeCreatingaNewFlowServiceon page 131. Code CONV001 Message and Description [ISC.0082.9101] Document type generation error: errorNumber. Cause: TheschemaprocessorencounteredanerrorintheXMLSchema definitionusedtocreateanISdocumenttype. Response: ContactSoftware AGSoftware AGGlobalSupport. DTDC001 [ISC.0082.9501] DTD is empty Cause: TheDTDdoesnotcontainanyinformation. Response: MakesurethattheDTDisvalid. DTDC002 [ISC.0082.9502] NS Declaration is missing for prefix 'prefixName' Cause: WarnsthatanXMLNamespaceprefixisusedwithoutdeclaring it. Response: DeclaretheXMLNamespaceprefixbeforeusingit. DTDC003 [ISC.0082.9503] Error while parsing' Cause: WarnsthataDTDcannotbeparsed.ItispossibletheDTDdoes notsatisfyXML1.0. DTDC005 [ISC.0082.9505] Name collision detailedWarningMessage Cause: Warnsthatanelementtypedeclarationisfoundinanother schemawiththesameXMLNamespace. Response: UseadifferentXMLNamespace.
497
Code XSDC001
Message and Description [ISC.0082.9703] Duplicate declaration found in this schema definition Cause: AduplicateattributeorelementdeclarationisfoundintheXML Schemadefinition. Response: MakesuretheXMLSchemadefinitionisvalid.
XSDC002
[ISC.0082.9704] Duplicate definition found in this schema definition Cause: Aduplicatesimpletypeorcomplextypedefinitionisfoundin theXMLSchemadefinition. Response: MakesuretheXMLSchemadefinitionisvalid.
XSDC003
[ISC.0082.9705] Definition not found Cause: Asimpletypeorcomplextypedefinitionismissingfromthe XMLSchemadefinition. Response: MakesurethedatatypedefinitionispresentintheXML Schemadefinition.
XSDC004
[ISC.0082.9706] Declaration not found Cause: Anerror.Anelementdeclarationorattributedeclarationis missingfromtheXMLSchemadefinition.
XSDC005
[ISC.0082.9707] Base type definition not found Cause: Abasetypedefinitionthatisusedtoderiveeitherasimpletype orcomplextypeismissingfromtheXMLSchemadefinition. Response: MakesurethebasetypedefinitionispresentintheXML Schemadefinition.
XSDC006
[ISC.0082.9708] Type derivation not OK Cause: Anerror.Asperthespec(s)fromtheW3C,thetypederivation isnotOK. [ISC.0082.9709] Type derivation not OK: attribute declaration to be restricted is not found in the base type definition Cause: Inacomplextypederivation,anattributedeclarationrestrictsthe useofanattribute.However,thisattributedeclarationisnotfoundin thebasetypedefinition. Response: Makesurethattheattributedeclarationispresentinthebase typedefinition.
498
Code
Message and Description [ISC.0082.9710] Type derivation not OK: attribute declaration to be prohibited is not found in the base type definition Cause: Inacomplextypederivation,anattributedeclarationprohibits theuseofanattribute.However,thisattributedeclarationisnotfound inthebasetypedefinition. Response: Makesurethattheattributedeclarationispresentinthebase typedefinition.
XSDC008
[ISC.0082.9712] Incorrect facet (s) specified: typeName throws errorMessage. Cause: Constrainingfacetsappliedtothedatatypeareincorrector cannotbeusedwiththedatatype. Response: Usetheerrormessagestodeterminewhichconstraining facetstoremovefromthetypedefinition.
XSDC009
[ISC.0082.9713] Unable to resolve QName Cause: IncorrectQName. Response: CheckthevalueoftheQName.
XSDC080
[ISC.0082.9701] Duplicate declaration found in this schema folderName:schemaNamewith the same target namespace Cause: Warnsthatanidenticalattributedeclarationorelement declarationisfoundinthespecifiedschemawiththesametarget namespace.Theschemaprocessorcreatestheschemabutdoesnot includetheduplicatedeclaration.Instead,theschemacontainsa pointertothefirst(original)declaration. Response: Nonerequired.
XSDC081
[ISC.0082.9702] Duplicate definition found in this schema folderName:schemaName with the same target namespace Cause: Warnsthatanidenticalsimpletypeorcomplextypedefinitionis foundinthespecifiedschemawiththesametargetnamespace.The schemaprocessorcreatestheschemabutdoesnotincludetheduplicate typedefinition.Instead,theschemacontainsapointertothefirst (original)typedefinition. Response: Nonerequired.
499
Code
Message and Description [ISC.0082.9106] Complex type TypeName is recursive. webMethods Integration Server does not support creating a document type from an XSD with a recursive complex type. Cause: TheXMLSchemacontainsarecursivecomplextypedefinition. TheIntegrationServerdoesnotsupportgeneratingadocumenttype fromanISschemacontainingarecursivecomplextype.Thiserroronly occurswhenyougenerateanISdocumenttypefromanXMLSchema. Response: Iftheschemayouareusingtogenerateadocumenttype containsarecursivecomplextypedefinition,selecttheGenerate complex types as document typesoptionwhenyoucreateanewdocumenttype fromanXMLSchemainDeveloper.
500
Index
Symbols
_env field 261 ! 447 != 444 " 451 ( 451 ) 451 / 451 \ 451 & 448 && 448 % 451 277 < 444 <= 445 <> 444 = 443 == 443 > 444 >= 444 | 447 || 447 $xmldata 367 adding folders 131 packages 76 transformers 229 variables to pipeline link 226 addressing variables in expressions and filters 449 variables with special characters 450 alarm events definition of 378, 391 reasons generated 391 uses of 391 all content model 243 Allow unspecified fields option 274 and operator 448 annotating source code for jcode 337 anonymous type definitions 243 any attribute declaration 242 any element declaration 242 anyURI content constraint 463 API for Java services 332 applying conditions to links 219 constraints to variables 273, 462 areas of Developer window behavior and operation 35 editor 31 focus 35 general layout 25 Navigation panel 26 Properties panel 33 Recent Elements tab 31 resizing 37 Results panel 35 switching perspectives 38 UDDI Registry tab 29 zooming 37 arithmetic services 229 array variables default behavior for linking 433 definition of 433 guidelines for linking 218 linking to or from array variables 216, 433 linking to or from scalar variables 216, 433 linking to transformers 232
A
access control 114 ACLs assigning to elements 114, 117 assigning to packages and folders 117 checking for services 115 defined 114 element creation, view, and deletion implications 122 inheritance 119 locking implications 121 requirements for using Developer 22 testing and debugging implications 121 viewing on a server 120 actions, performing on IS elements 36 adapter notifications described 262 guidelines for moving and copying 53 adapter services, retry behavior 401
501
Index
assigning default value to a variable 222 replication services 90 shutdown services 90 startup services 90 universal names to services 154 values to pipeline variables 221, 222 variable values to a variable 223 version numbers to packages 83 attribute declaration 242 reference 242 audit data, when generated 158 audit events definition of 378, 392 when generated 158 Audit level property 165 auditing configuring 157 failed and successful services 159, 163 failed services 159 for errors 162 for recovery, described 163 for resubmission purposes 162 long-running services 164 service retry 151 services 157 use cases 162 auditing options overwritten by server property 165 setting for a service 164 auditLog server property 165
B
base64Binary content constraint 463 blank labels in BRANCH steps 180 blue links, in the Pipeline tab 217 booleans content constraint 463 in filters, Broker restrictions 453 BRANCH step branching on empty values 180 branching on expressions 179 branching on null values 180 branching on switch value 176 creating 184 creating a multi-step child for 182 definition of 128, 408
Evaluate labels property 179 specifying default step 181 specifying label value 177 specifying switch variable 177 switch value 176 using conditional expressions 179 using in a flow 176 using SEQUENCE as a target of 182 using with regular expressions 177 breakpoints and the Trace Into command 307 clearing from flow steps 308 clearing from transformers 308 listing all 309 locating in flow services 309 overview 307 point when processing halts 307, 308 removing 309 setting in flow services 307 setting on a flow step 307 setting on a transformer 308 Broker filter collation locale 445 filter rules 452 Broker document type, creating publishable document type from 259 Broker document types using to create publishable document type 259 Broker/local trigger definition of 27 Broker/local triggers creating filters for 438 browser clients creating 360 invoking services from 361, 362 testing from 298 building event handler sample 388 event handlers 387 flow services 126 built-in services for arithmetic operations 229 for date/time transformations 229 for document (IData object) validation 281 for pipeline validation 282 for remote services 174 for string manipulation 229 for XML validation 282 invoking 174 throwExceptionForRetry 153 byte content constraint 463
502
Index
C
C/C++ clients creating 353, 354 creating a make file 354 C/C++ services compiling with a make file 341 creating 341, 342 caching definition of 142 elements to improve Developer performance 70 services not suited for 143 services suited for 143 setting 145 using prefetch 144 call stack 296 catch sequence, in service retry 401 changing level of a step 171 passwords 41 position of a step 170 child flows described 171 stepping in/out of child flows 305 tracing 303 choice content model 243 circular dependencies, between packages 87 class files location of 335 clearing breakpoints on flow steps 308 breakpoints on transformers 308 client applications creating browser-based 360 creating C/C++ 353 creating Excel 358 creating Java 350 creating Visual Basic 355 closed documents, described 274 closing a session on webMethods Integration Server 39 coded services, about 326 collapsing transformers 235 white space 474 COM objects invoking as services 345 using with webMethods components 345 COM services creating 345
com.wm.app.b2b.server.ISRuntimeException class 153 combining Trace and Step commands 301 commands Disable Step 310, 311 Enable Step 310, 311 Load Pipeline Locally 318 Reset 301 Restore Pipeline from Server 318 Restore Pipeline Locally 318 Save Pipeline from Server 318 Save Pipeline Locally 316 Save Pipeline to Server 316 Set Breakpoint 307 Step 300, 304, 305 Step Into 300, 304, 305 Step Out 304, 305 Trace 300, 302 Trace Into 300, 302, 303 Trace to Here 300, 302, 303 comments for jcode 337 Comments property, definition 172, 412 compiling C/C++ services 344 error in Java compiler location 333 Java services 333, 338 services with Developer 333 services with jcode 338, 340 specifying the Java compiler 333 complex type definition all content model 243 anonymous 243 choice content model 243 described 243 empty content 243 expanding as inline IS document type 254 generating as separate IS document types 254 mixed content 243 recursive structures 254 sequence content model 243 composite mode (jcode) 339 conditional expressions addressing variables 449 addressing variables with special characters 450 lexical operators 445 logical operators 447 operator precedence 448 standard relational operators 443 syntax 439 using with pipeline links 219 using with the BRANCH step 179
503
Index
conditional links creating 221 described 219 disabling 312 conditions applying to links 219 disabling on links 312 connecting to webMethods Integration Server 23, 39 constraining facets applying 277 described 273, 473 for pipeline validation 462 constraints content 240, 463 definition of 273 for IS schemas 240 for XML validation 240 structural 240 viewing for variables 277 content constraints applying to variables 273 constraining facets 273, 473 editing for simple types 248 for String variables, definition of 463 for validation 463 for variables, definition of 273 for XML validation 240 in IS schemas 240 in IS schemas, definition of 240 content models all 243 choice 243 empty 243 mixed 243 sequence 243 content types applying to variables 274 constraint symbol 277 customizing 276 specifiying constraining facet values 277 context-sensitive menus 36 Control steps BRANCH 128, 176 EXIT 128, 198 LOOP 128, 194 REPEAT 128, 186 SEQUENCE 128, 192
converting string lists to document (IData object) lists 215 copying by reference, definition of 211 by value, definition of 211 elements from the Results panel 295 IS elements 51 pipeline values 224 set values 224 transformers 234 creating code for Java services 333 event filters 383 event filters for services 385 event handler sample 388 event handlers 387 flow services 130, 131 folders 131, 341 IS elements 45 IS schemas 245 Java services with an IDE 337 Java services with C/C++ 341 Java services with Developer 329, 332 Java services with Visual Basic 345 Java services with your own IDE 335 links to array variables 433 links to document (IData object) variables 213 packages 76 specifications for C/C++ services 341 version numbers for packages 83 cursors 327 customizing content types 276
D
dagger symbol, next to variable icon 277 data transformations, definition of 202 data types icons to represent 133 linking with Pipeline tab 214 supported by webMethods Integration Server 430 tables 433 data validation allowing undeclared variables 274 applying constraints 273 benefits of 272 blueprints for 272 closed variables 274 content constraints 273
504
Index
definition of 272 document (IData object) validation 281 errors 478 exceptions 284, 492 input/output validation definition of 278 performing via Input/Output tab 279 performing via INVOKE step properties 280 open variables 274 pipeline validation 281 requiring variable existence 274 structural constraints 273 types of 272 XML validation 282 date content constraint 464 date conversion services 229 dateTime content constraint 464 DCOM objects invoking as services 345 using with webMethods Integration Server 345 debug level, setting on server 321 debugging flow services breakpoints 307 combining trace and step 301 disabling a single flow step 310 disabling a transformer 311 disabling conditions on links 312 dumping the pipeline to serveryyyymmdd.log 323 enabling a single flow step 310 enabling a transformer 311 modifying the pipeline 313 overview 288, 299 resetting debug mode 301 stepping into a child flow 305 stepping into a transformer 306 stepping through a flow 300, 304 tracing a flow 300, 302 tracing into a child flow 303 using server debug facility 320, 321 debugLog service 322 decimal content constraint 464 declaring input and output parameters 133 input for a service 133 output for a service 135 default value, assigning to a pipeline variable 222 defining packages 76
deleting breakpoints on transformers 308 event subscriptions 387 IS elements 58 links between variables 219 packages 82 dependencies, package identifying 86 removing 87 dependents checking when renaming IS elements 47 confirming before deleting elements 47 finding service and document (IData object) 64 safeguards for updating 48 details perspective 38 Developer window, toolbar 30 Developer. See webMethods Developer dimensionality, definition of 233 directories Java services 335 Disable Step command 310, 311 disabling a condition placed on a link 312 a flow step 310 a transformer 311 dispatch services for COM 345 for DCOM 345 document (IData object) validation definition of 281 errors 478 exceptions 492 performing 281 document data type 430 document list data type converting from String list 215 definition of 430 document reference data type creating 264 definition of 430 document reference list data type creating 264 definition of 430 Document Type Definitions. See DTDs document types. See IS document types documentation accessing for packages 81 creating for packages 80 using effectively 17
505
Index
documents (IData objects) applying content constraints 462 assigning to a document or document list 250, 265 assigning to a specification 250 benefits of 250 creating 250 errors when creating from DTD or XML Schema 497 finding dependents 47 linking 213 open and closed 274 pipeline validation 282 printing 263 using as service parameters 250, 264 viewing in browser 263 double content constraint 465 DROP modifier 206, 225 dropping values from the pipeline 225 DTDs creating documents (IData objects) from 250 creating IS document types from 252 creating IS schemas from 245 IS schema generation warnings 497 duration content constraint 465
E
edit perspective 38 editing elements. See editor event subscriptions 386 flow services 126 properties 34 Service property 173 simple types in IS schema 248 editor described 31 help about 42 hiding and showing 37 inserting flow steps into 169 resizing 37 supported data types 133 tabs 31 viewing and editing elements in 32 element declaration 242 element lock copying, moving, and deleting 104 removing. See unlocking elements system lock 98 user lock 98
element reference 242 elements (IS) See also editor 47 assigning ACLs 117 caching to improve Developer performance 70 copying 51 creating 45 cutting 51 definition of 44 deleting 58 displayed in editor 31 displayed in Navigation panel 26 displayed in Recent Elements tab 31 displayed in UDDI Registry tab 29 double-clicking to open 49 editing 47 exporting 82 finding dependents 47 finding in Navigation panel 60 finding unresolved references 66 fully-qualified names 45 guidelines copying 51 creating 45 deleting 58 general actions 48 moving 51 opening and closing 49 renaming 55 help for properties 42 locating in Navigation panel 33 locking 47 moving 51 naming guidelines 46 overwriting when creating publishable document types 259 pasting 51 performing actions 48 performing actions on 36 permissions 114 references 65 renaming 55 saving 57 single-clicking does not open 49 unlocking 47 viewing as HTML 47 emailing XML to a service 374
506
Index
empty content 243 strings in filters 445 values, branching on 180 Enable service audtiting options, described 158 Enable Step command 310, 311 enabling flow steps 310 service auditing 158 transformers 311 end-to-end linking 228 entering input for a service 290 ENTITIES content constraint 465 ENTITY content constraint 465 enumeration constraining facet 473 envelope field in publishable document types 261 usage restrictions 261 error auditing, described 162 error handling, in flow services 192 errors data validation 478 document (IData object) generation 497 flow service generation 497 IS schema generation 497 pipeline validation 478 Evaluate labels property 184 event filters creating 383 creating for services 385 event handlers creating 387 creating sample 388 definition of 380 stages of creating 387 Event Manager alarm events definition of 378, 391 uses 391 audit events definition of 378, 392 definition of 378 event behavior 380 event handlers 380 Event Manager command 381 exception events 378, 392 filters 383 GD End events 392 uses 392
GD Start events 392 uses 392 guaranteed delivery events 378 JMS Retrieval Failure Events 394 JMS retrieval failure events 378, 384 pattern strings 383 port status events 379, 395 uses 395 replication events 379, 395 uses 395 run-time behavior 380 security events 379, 395 session end events 396 session events 379, 396 uses 396 session expire events 396 session start events 396 stat events 379, 397 uses 397 subscriptions creating 381 creating filters for 383 deleting 387 editing 386 managing 381 suspending 386 viewing 386 transaction events 379, 397 Tx End events 397 uses 397 Tx Start events 397 uses 397 viewing subscriptions 386 Event manager JMS delivery failure events 378, 384 events See also event handlers, Event Manager creating filters 383 creating filters for services 385 deleting subscriptions to 387 editing subscriptions to 386 guaranteed delivery 392 subscribing to 381 suspending subscriptions to 386 types of 378 viewing subscriptions to 386 Excel clients, creating 358 exception events definition of 378, 392
507
Index
exceptions data validation 284, 492 during a test 295 executing services from Developer 289 execution locale 145 Exit on property 192 EXIT step creating 198 definition of 128, 410 using in a flow 198 expanding complex types inline 254 expanding transformers 235 explicit linking, definition of 208 explicit universal names 155 exporting elements and packages 82 expressions addressing variables 449 addressing variables with special characters 450 branching on 179 operator precedence 448 operators for 442 syntax for 439 using for pipeline linking 219 extending the Java class 331 extends (Java keyword) 331
F
facets, See constraining facets failIfInvalid property 492 failure of a flow step 192 of a REPEAT step 187 fields content type constraint symbol 277 dagger symbol 277 green squares 277 optional symbol 277 filter collation locale 445 filtering events 383 filters addressing variables 449 addressing variables with special characters 451 allowed quantifiers 453 back references 453 booleans in 453 braces {} in 453 checking for variable existence 453
collation locale, specifying 445 comparing strings and numeric values 453 comparison operators, missing 453 constrained Objects in 453 effect of locale 445 extended metacharacters 453 lexical relational operators 445 logical operators 447 $null 453 operators for 442 server performance 443 standard relational operators 443 syntax 439 syntax restrictions 452 variables with special characters 450 finding elements in Navigation panel 60 invoked services 63 service and document (IData object) dependents 64 unresolved pipeline references 67 unresolved references 66 float content constraint 465 flow services See also services, debugging flow services breakpoints 307 caching to improve Developer performance 70 creating 131 debugging 299 definition of 126 disabling a single step 310 disabling a transformer 311 disabling conditions placed links 312 editing 126 enabling a single step 310 enabling a transformer 311 errors creating from DTD or XML Schema 497 inserting steps in a service 169 maximum retry period 152 printing 166 response to failure 192 retrying 151, 152 stages of creating 130 stepping in/out of child flows 305 stepping in/out of transformers 306 stepping through 304 tracing 302 viewing in browser 166
508
Index
flow steps BRANCH 128, 176 changing the level of 170 changing the position of 170 definition of 127 disabling 310 enabling 310 EXIT 128, 198 failure of 192 grouping 192 hierarchical order of 171 inserting into a flow service 169 INVOKE 127, 173 LOOP 128, 194 MAP 127, 200 moving in a flow service 170, 171 parent/child relationships 171 properties 172 re-enabling 310 REPEAT 128, 186 SEQUENCE 128, 192 setting breakpoints on 307 folders, creating 131 frag mode (jcode) 339 FTPing XML to a service 371
G
GD End events definition of 392 pub.remote.gd:end 392 uses of 392 when generated 393 GD Start events definition of 392 pub.remote.gd:start 392 uses of 392 when generated 393 gDay content constraint 466 Generate Code command 352, 354, 356 generating complex types as document types 254 global declarations, in XML Schemas and DTDS 242 gMonth content constraint 466 gMonthDay content constraint 466 Go To Breakpoint command 309 Go To command (for services) 63 gray links, in the Pipeline tab 207
green square, next to variable icon 277 grouping flow steps 192 guaranteed delivery events See also GD End events, GD Start events compared to transaction events 393 definition of 378, 392 generating guaranteed delivery (GD) events 393 generating transaction (Tx) events 393 overview 393 when generated 393 guidelines for assigning startup, shutdown, and replication services 89 for creating IS document types 252 for elements creating 45 deleting 58 moving and copying 51 opening and closing 49 renaming 55 working with 48 for linking array variables 218 for linking document (IData object) variables 213 for linking variables 209 for linking variables of different data types 214 for naming packages 76 gYear content constraint 467 gYearMonth content constraint 467
H
hailmary mode (jcode) 340 hard-coding input variables 221 help, obtaining 42 hexBinary content constraint 467 hiding and showing panels 37 HTML, viewing elements in 47
I
ID content constraint 467 IData objects creating 327 definition of 326 getting data from 327 positioning cursors 327 putting data in 327 using in a Java service 336
509
Index
IDE assigning a super class with 331 creating source code in 329 defining private methods with 331 implementing interfaces with 331 importing Java packages 331 in Developer 328, 329 using other IDEs 335 using the Java service editor 329 using the Shared tab 331 identifying package dependencies 86 replication services 90 shutdown services 90 startup services 90 IDREF content constraint 468 IDREFS content constraint 468 implementing interface in Java services 331 implements (Java keyword) 331 implicit linking described 207 for MAP steps 228 implicit universal names 155 import (Java keyword) 331, 336 import mechanism, in XML Schemas 247 importing Java packages 331, 336 include mechamism, in XML Schemas 247 index, array variables 217 Indexing tab. See linking array variables Input array property 195 input variables declaring for a service 133 declaring in a document (IData object) 250 entering test values for 290 hard-coding 221 linking considerations 209 linking in the pipeline 208 loading values from a file 292 saving values to a file 292 input/output parameters declaring for a service 133 generating Java code from 333 Input/Output tab 135 input/output validation definition of 278 performing via Input/Output tab 279 performing via INVOKE step 280
inserting INVOKE step 174 steps into flow services 169 transformers 229 installing Java services 335 int content constraint 468 integer content constraint 468 Integrated Development Environment. See IDE Integration Server Administrator, unlocking elements 106 Integration Server. See webMethods Integration Server interfaces implementing in Java service 331 INVOKE step Comments property 412 creating 174 definition of 127, 412 finding 63 invoking built-in services 174 invoking services on another server 174 Label property 412 peforming validation via step properties 280 Pipeline tab 203 Scope property 412 Service property 173, 412 Timeout property 412 using in a flow 173 Validate input property 412 Validate output property 412 invoking built-in services 174 remote services 174 services 174 services from a browser 361, 362 services on another server 174 IS document types See also documents (IData objects) creating empty document types 251 creating from Broker document type 259 creating from DTD 252 creating from XML document 252 creating from XML Schema 252 described 250 editing 263 expanding complex types inline 254 generating complex types as document types 254 guidelines for creating 252
510
Index
IS elements. See elements (IS) IS schemas appearance 240 constraints 240 content constraints 240 creating 245 definition of 240 editing simple types 248 errors from generating 497 generating multiple 247 import element 247 include element 247 structural constraints 240 using to validate an XML document 282 warnings from generating 497 ISRuntimeExceptions description of 151 throwing in services 400
jcode utility composite mode 339 frag mode 339 hailmary mode 340 make mode 338 purpose of 336 source code samples 456 source code tags 337 update mode 340 JMS delivery failure event 378, 384 JMS retrieval failure events 378, 384 JMS trigger definition of 27
K
keyboard shortcuts 36
L
L_EQUALS 446 L_GREATER_OR_EQUAL 446 L_GREATER_THAN 446 L_LESS_OR_EQUAL 446 L_LESS_THAN 446 L_NOT_EQUALS 446 Label property definition 412 for evaluating expressions 179 for general use 172 for specifying the default BRANCH step 181 for targeting BRANCH steps 177 language content constraint 468 length constraining facet 473 lexical relational operators conditional expressions 445 definition of 445 empty string 445 locale 445 non-string variables 445 libs directory 341, 344 link indices 217 linking array variables 216 default rules 433 guidelines for 218 to array variables 433 to scalar variables 433 to transformers 232 between document formats 228
J
Java classes for object and object list variables 431 Java clients, creating 350, 352 Java keywords extends 331 implements 331 import 331, 336 Java service editor 329 Java services adding private methods to 331 compiler location 333 compiling with Developer 333 compiling with jcode 338 creating 332, 333 creating with an IDE 335, 337 creating with Developer 329 extending the class of 331 implementing interface in 331 importing packages into 331, 336 installing manually 335 jcode requirements 337 location of class files 335 location of source files 336 publishing to the server 335 required code 336 setting run-time options 335 stages of development 329 structure of 328 using with webMethods components 328 validating from 283
511
Index
conditional links 219 considerations 209 copying by reference 211 copying by value 211 default behavior for arrays 218 deleting links between variables 219 different data types 214 disabling conditions on links 312 document (IData object) variables 213 in a single view 228 input variables 208 output variables 209 pipeline variables to service variables 207 scalar variables to array variables 433 the pipeline 210 transformers 231 variables conditionally 219 variables explicitly 208 variables implicitly 207 links blue colored 217 deleting 219 disabling conditions 312 executing at run time 211 gray colored 207 in Pipeline tab 207 Load Pipeline Locally command 318 loading input values from a file 292 pipeline values from a file into Results panel 318 with restorePipelineFromFile service 319 locating a breakpoint 309 locking elements corresponding server files 108 description 98 Java and C/C++ 101 single element 101 system locking 102 template service 102 unlocking. See unlocking elements VCS check in/check out 98 viewing lock status 99, 103 log files, audit log 158 logging on to webMethods Integration Server 23, 39 logical operators, definition of 442 long content constraint 469
LOOP step creating 196 creating nested loops 194 definition of 128, 413 setting Input array 195 setting Output array 196 using in a flow 194
M
make file creating 341 using to compile C/C++ services 344 make mode (jcode) 338 MAP modifier definition of 206 executing at run time 211 linking different data types 214 linking from service output 209 linking to service input 208 MAP step debugging 306 definition of 127, 414 disabling transformers 311 enabling transformers 311 inserting transformers 229 Pipeline tab 205 transformers 228 using in a flow 200 using to initialize variables in a flow 200, 222 mapping. See linking Max attempts property 153 maxExclusive constraining facet 473 maximum retry period, definition of 152 maximum retry period, description of 152 maxInclusive constraining facet 473 maxLength constraining facet 473 maxOccurs threshold value, for validation 285 memory reducing usage 70 running out of during validation 285 menu bar, using to perform actions 36 metacharacters, in filters 453 methods, adding to a Java service 331 minExclusive constraining facet 474 minInclusive constraining facet 474 minLength constraining facet 474 mixed content 243 modifying the pipeline 206 moving IS elements 51 steps in a flow service 170 steps within a flow 171
512
Index
N
Name content constraint 469 name transformations, definition of 202 namespace information (for services) creating source file from 339, 340 location of 335 updating with jcode 339 namespaces usage in universal names 154 XML namespace property 266 naming services 45 Navigation panel described 26 help about 42 hiding and showing 37 icons 26, 99 refreshing contents of 29 resizing 37 toolbar 30 NCName content constraint 469 negativeInteger content constraint 469 NMTOKEN content constraint 469 NMTOKENS content constraint 469 nonNegativeInteger content constraint 470 nonPositiveInteger content constraint 470 not operator 447 notification, of server shutdown 40 ns directory 335 $null in filters 453 in labels for BRANCH steps 180 null, branching on 180
operators conditional expressions and filters 442 lexical relational operators 445 logical 447 precedence in expressions 448 relational 442 standard relational operators 443 optional variables for validation 274 or operator 447 out of sync publishable document types 263 Output array property 196 output templates assigning to a service 138 definition of 138 output variables declaring 135 declaring for a service 133 declaring in a document (IData object) 250 linking considerations 209 linking in the pipeline 209 Overwrite Pipeline Value option 222
P
packages adding 76 assigning version numbers 83 copying 79 creating 76 creating circular dependencies 87 cutting 79 definition of 74 deleting 82 dependencies, using with startup services 88 documenting 80 exporting 82 identifying dependencies 86 importing into Java services 331, 336 moving 79 naming guidelines 76 pasting 79 reloading 81 reloading vs refreshing 81 removing dependencies 87 required by Java services 336 viewing details 77 viewing patch history 84
O
Object data type definition of 431 in filters 453 Object list data type, definition of 431 object list variables, Java classes 431 object variables, Java classes 431 online help, obtaining 42 open and closed documents 274 open documents, described 274 opening a session on webMethods Integration Server 39 operations, performing on IS elements 36
513
Index
panels editor 31 Navigation 26 Properties 33 Recent Elements 31 Results 35 switching perspectives 38 UDDI Registry 29 parameters applying constraints 273 benefits of declaring 133 declaring 133, 136 declaring for a service 133, 135 parent/child relationships in a flow 171 passing XML to a service 366 passwords changing 41 requirements 41 patch history removal by Integration Server 85 viewing for a package 84 pattern constraining facet 474 pattern matching, in event subscriptions 383 Perform Variable Substitution option 223 Performance 161 performance impact, service auditing 161 permission See also ACLs assigning to elements 114 Permissions property 118 perspectives of views 38 pipeline adding variables to 226 addressing variables 449 adjusting 206 assigning values to 221 changing values 313 checking for variables 442 conditional linking 219 copying values 224 definition of 128 DROP modifier 225 dropping values 313 dropping variables from 225 inspecting modifiers 67 linking 210 array variables 216 default rules 433 guidelines for 218 input variables 208
output variables 209 scalar variables, default rules 433 transformers 231 variables of different data types 214 MAP step 200 modifying 313 Overwrite Pipeline Value option 222 Perform Variable Substitution option 223 Pipeline In 203 Pipeline Out 204 saving 315 saving from Results panel 316 saving with savePipelineToFile service 317 Service In 203 Service Out 204 SET VALUE modifier 221 stages of 203 validating 282 validating via built-in services 282 validating via Java service 283 viewing after run-time exception 297 viewing with Developer 293 Pipeline Editor. See Pipeline tab Pipeline In 203, 205 pipeline modifiers definition of 206 DROP 206 MAP 206 SET VALUE 206 Pipeline Out 204, 205 pipeline references definition of 67 finding 67 Pipeline tab 202 blue links (conditional link) 217 copying by reference 211 copying by value 211 default behavior for arrays 218 default linking rules 433 deleting links between variables 219 editing a MAP step 205 editing INVOKE step 203 gray links (implicit link) 207 inserting transformers 229 linking array variables 216 default rules 433 guidelines for 218
514
Index
document (IData object) variables 213 scalar variables, default rules 433 transformers 231 variables 207 overview 202 printing 206 transformer movement 232 viewing in browser 206 pipeline validation definition of 281 errors 478 exceptions 492 performing via built-in services 282 performing via Java service 283 port status events definition of 379, 395 uses of 395 positiveInteger content constraint 470 posting XML to a service 369 precision constraining facet 474 prefetch 144 preserve white space 474 printing documents (IData objects) 263 flow services 166 Pipeline tab contents 206 private methods, defining in Java service 331 programming languages creating services with 326 supported 326 properties Audit level 165 auditLog server 165 Comments 172, 412 definition of 172 editing 34 Evaluate labels 184 Exit on 192 for transformers 230 Input array 195 Label 172, 412 Label (for BRANCH steps) 177, 181 Output array 196 Permissions 118 Repeat on 186, 187, 188, 417 Scope 184, 412 Service 173, 175, 230, 412 setting for variables 265
Substitution groups 256 Switch 177, 184 Timeout 175, 184, 188, 189, 196, 412 Validate input 175, 230, 412 Validate output 175, 230, 412 XML Namespace 266 Properties panel auditing a service 157 described 33 flow step properties 172 help about 42 hiding and showing 37 patch history for packages 84 resizing 37 run-time parameters 141 pub.flow:getRetryCount service 153 pub.flow:throwExceptionForRetry service 153 invoking 403 pub.publish:envelope document type 261 pub.remote:invoke service 174 pub.remote.gd:end service 392 pub.remote.gd:start service 392 pub.schema:validate service 281 pub.schema:validatePipeline service 282 publishable document types adapter notifications 262 creating from Broker document type 259 defined 259 editing 263 envelope field 261 overwriting elements 259 synchronizing 263 publishing services to the server 335
R
Recent Elements tab described 29, 31 help about 42 hiding and showing 37 resizing 37 Record data type. See document data type Record list data type. See document list data type Record Reference data type. See document reference data type Record Reference List data type. See document reference list data type records. See document (IData object), IS document types
515
Index
recursive complex types in XML Schemas 256 redefine mechanism, in XML Schemas 247 re-enabling flow steps 310 transformers 311 referenced elements, importing during synchronization 260 references finding 65 inspecting pipeline 67 refresh difference from restoring a session 40 Navigation panel contents 29 Recent Elements tab contents 31 regular expressions creating event filters with 385 definition of 422 operators 422 using as a BRANCH label 177 using in a mask 422 reinvoking services 162 relational operators definition of 442 lexical 445 standard 443 types of 442 reloading packages 81 remote servers, invoking services on 174 remote services, invoking 174 removing breakpoints 309 breakpoints from transformers 308 package dependencies 87 packages 82 replication services 91 shutdown services 91 startup services 91 variables from the pipeline 225 renaming IS elements 55 transformers 236 Repeat on property 186, 187, 188, 417 REPEAT step creating (on failure) 188 creating (on success) 190 definition of 128, 415 failure 187 specifying the repeat condition 186, 187, 417
using in a flow 186 using to retry a failed step 188 using to retry a successful step 190 replace white space 474 replication events definition of 379, 395 uses of 395 replication services assigning 90 definition of 89 guidelines for assigning 89 removing 91 when to use 89 requirements for passwords 41 requiring variable existence for validation 274 Reset command 301 resizing panels 37 window areas 37 Restore Pipeline from Server command 318 Restore Pipeline Locally command 318 restorePipelineFromFile service 315, 318 restoring pipeline values from a file into Results panel 318 with restorePipelineFromFile service 319 sessions 40 Results panel copying elements from 295 described 35 general information 294 help about 42 hiding and showing 37 resizing 37 saving results from 315 retried audit log status 151 Retry interval property 153 Retry on ISRuntimeException category 153 retry period, maximum 152 retry, for service 151 retrying a flow step 186 Run command 289 Run in Browser command 298 running out of memory, during validation 285 running services from Developer 289 run-time exceptions 295 run-time settings 335
516
Index
S
Save Pipeline Locally command 316 Save Pipeline to Server command 316 savePipelineToFile service 317 saving changes to elements 57 elements (IS) 57 input values to a file 292 test results using savePipelineToFile service 317 test results, overview 315 scalar variables default behavior for linking 433 definition of 433 linking to or from array variables 433 scale constraining facet 473 schema browser, definition of 241 schema details area, definition of 244 schema domains 245 schema editor 240 schema processor, definition of 245 schema services for document (IData object) validation 281 for pipeline validation 282 for XML validation 282 Scope property, definition 412 Send XML File command 299 sending XML documents to a service 366 via email 374 via FTP 371 via HTTP 369 sequence content model 243 SEQUENCE step as target for a BRANCH 182 definition of 128, 418 setting exit condition 192 using in a flow 192 server files, viewing for locked elements 108 server. See webMethods Integration Server serveryyyymmdd.log file 321 contents of 321 dumping pipeline to 323 overview 320 service auditing configuring 157 described 157 enabling 158 error auditing 162
failed and successful services 163 including pipeline 160 overwriting individual service settings 165 performance impact 159, 161 specifying which states to log 158 use cases 162 Service In 203 service log configuring 157 described 158 Service Out 204 Service property definition 412 definition of 173 editing 173 for transformers 230 renaming transformers with 236 service retry adapter services 401 audit log 151 basic componenents 401 configuring 151 example 404 overview 400 requirements 152, 400 restrictions 152 throwing exceptions for 400 services assigning universal names 154 audit data enabling 158 when generated 158 auditing configuring 157 enabling 158 for recovery 163 long-running services 164 options 164 caching to improve Developer performance 70 configuring retry 151 creating event filters for 385 creating flow 131 creating with Visual Basic 345 execution locale 145 finding dependents 47 finding invoked 63 input signature for trigger services 134 invoking built-in 174
517
Index
invoking on another server 174 invoking on remote servers 174 locale policy 145 naming 45 provided by webMethods Integration Server 174 reinvoking 162 retry exceptions 400 retryiing 152 retrying adapter services 401 stages of creating 130 state information 141 testing and debugging 288 throwing retry exceptions 400 transformers 227 validating input/output via Input/Output tab 279 validating input/output via INVOKE step 280 session closing on webMethods Integration Server 39 opening on webMethods Integration Server 39 restoring 40 session end events definition of 396 session events See also session end events, session expire events, session start events definition of 379, 396 uses of 396 session expire events definition of 396 session start events definition of 396 Set Breakpoint command 307 SET VALUE modifier 206, 221 copying 224 using in MAP step 222 setting breakpoints on flow steps 307 breakpoints on transformers 308 variable values 221 Settings tab. See Properties panel Shared tab 331 short content constraint 470 shortcuts, for toolbars 30 showing and hiding panels 37 shutdown services assigning 90 definition of 89 guidelines for assigning 89 removing 91 when to use 89
signature for trigger services 134 of a service 326 simple types 243 editing in IS schema 248 single view linking 228 smtp, using to submit XML documents 374 source code compiling with C/C++ make file 344 compiling with jcode 338, 340 creating automatically for a Java service 333 creating from namespace information 339 creating in your own Java IDE 336 creating Java 334 location of 336 tagging for jcode 337 writing in C/C++ 343 writing in Developer 329 source control system, integration with 98 Source field on Shared tab 331 Source tab. See Java service editor special characters in variable names 450 typing in expressions 451 specifications assigning to a service 269 benefits of 267 creating 267 definition of 267 finding dependents 47 squares, green 277 stack overflow, during validation 285 standard relational operators definition of 443 using in filters 443 using in triggers 443 starting Developer 23 startup services assigning 90 definition of 88 effect on package dependencies 88, 91 guidelines for assigning 89 removing 91 when to use 88 stat events definition of 379, 397 uses of 397 state information for a service 141
518
Index
status events. See port status events Step command 300, 304, 305 Step Into command 300, 304, 305 Step Out command 304, 305 stepping through a flow 300, 304 string content constraint 471 String data type, definition of 430 String list data type converting to document list 215 definition of 430 String table data type 430 strings copying by reference 211 transformation services 229 structural constraints definition of 240, 273 for validation 273 for XML validation 240 IS schemas 240 structural transformations definition of 202 examples 215 linking to resolve 214 subordinate flow steps. See child flows subscribing to events, overview 381 Substitution group property 256 substitution groups 256 super class, defining in IDE 331 suspending event subscriptions 386 Switch property 177, 184 switch value, branching on 176 symbol for content type constraints 277 for optional variables 277 syntax for conditional expressions and filters 439 system locking defined 98 elements 102
T
tables, support of 433 tabs Input/Output tab 135 Pipeline tab 202 Schema tab. See schema editor 240 selecting 31 Settings tab for services. See also Properties panel 335 Shared tab 331
tagging source code for jcode 337 templates assigning to a service 138 definition of 138 test perspective 38 test results changing pipeline values 313 copying 295 loading 315 saving 315 viewing 293 testing services entering test input 290 from a browser 298 from Developer 289 inspecting the pipeline 293 loading input values from a file 292 loading the pipeline 315 overview 288 run-time exceptions 295 saving input to a file 292 saving the pipeline 315 setting breakpoints 307 testing in debug mode 299 viewing results 293 viewing the call stack 296 viewing the pipeline 297 XML document as input 299 threshold value, for maxOccurs 285 throw exception for retry 401 time content constraint 471 time conversion services 229 timeDuration content constraint 465 Timeout property 175 definition 412 for BRANCH step 184 for LOOPstep 196 for REPEAT step 188, 189 token content constraint 471 toolbar, Developer window 30 toolbar, using to perform actions 36 totalDigits constraining facet 474 Trace command 300, 302 Trace Into command 300, 302, 303, 304 and breakpoints 307 effect on breakpoints 307 Trace to Here command 300, 302, 303 tracePipeline service 323
519
Index
tracing a flow 300, 302 into a child flow 303 transaction events See also Tx End events, Tx Start events compared to guaranteed delivery events 393 definition of 379, 397 uses of 397 when generated 393 Transformer not found message 236 transformers adding 229 array variables 232 clearing breakpoints 308 collapsing 235 considerations 229 copying 234 debugging 306 definition of 227 dimensionality mismatch 232 disabling 311 enabling 311 expanding 235 inserting 229 linking 231 linking array variables 232 movement in Pipeline tab 232 output variables 231 properties 230 re-enabling 311 renaming 236 Service property 230 services provided by webMethods 229 setting breakpoints 308 stepping in/out of child flows 306 Validate input property 230 Validate output property 230 validating input and output 234 zooming in on 235 transient error, definition of 151, 400 trigger services, input signature requirements 134 triggers disabled when copied 52 filter syntax restrictions 452 filters and relational operators 445 lexical operators 442 testing 288 used with adapter notifications 262 using standard relational operators 443
try sequence, in service retry 401 Tx End events definition of 397 uses of 397 when generated 393 Tx Start events definition of 397 uses of 397 when generated 393 type definitions anonymous 243 complex types 243 simple types 243
U
Unicode, and Java source code 339 universal names assigning to services 154 implicit vs explicit 155 local portion of name 154 namespace portion of name 154 removing from a service 156 unlocking elements more than one 104 system locked 107 using Integration Server Administrator 106 using webMethods Developer 105 unresolved references, finding 66 unsignedByte content constraint 471 unsignedInt content constraint 472 unsignedLong content constraint 472 unSignedShort content constraint 472 update mode (jcode) 340 URL, invoking services from 361, 362 user account on webMethods Integration Server 22
V
Validate input property 175, 230 definition 412 Validate output property 175, 230 definition 412 validatePipeline service 282 validating See also validation documents (IData objects) 281 from Java services 283 input/output for transformers 234 input/output via Input/Output tab 279
520
Index
input/output via INVOKE step 280 pipeline via built-in services 282 pipeline, overview 281 service input/output 278, 279, 280 XML documents 282 validation See also validating allowing undeclared variables 274 applying constraints 273 benefits of 272 blueprints for 272 constraining facets 473 constraints, definition of 273 content constraints 463 definition of 272 errors 284, 478 exceptions 284, 492 input/output 278 overview 272 requiring variable existence 274 running out of memory 285 service input and output 278 stack overflow 285 types of 272 XML validation 282 validation errors and error codes 478 validation services pub.schema:validate 281, 282 pub.schema:validatePipeline 282 value transformations, definition of 202 variables adding to the pipeline 226 addressing in the pipeline 449 applying constraints 273 applying content constraints 462 applying content types 274 checking for existence 442 content type constraint symbol 277 copying by reference 211 copying by value 211 copying values in pipeline 224 declaring for a service 133, 135 declaring in a document (IData object) 250 deleting links 219 initializing values 222 linked by blue line 217 linking 207 linking conditionally 219
optional existence for validation 274 optional symbol 277 requiring existence for validation 274 setting properties 265 substitutions 223 using as Set Value 223 viewing applied constraints 277 XML Namespace property 266 VCS Integration feature, described 98 version control system (VCS), integration with 98 version numbers, assigning to packages 83 View as HTML command 166, 206, 263 view perspectives 38 viewing assigned value of a variable 222 breakpoints list 309 elements in HTML 47 status of a locked element 99, 103 test results 293 variable constraints 277 Visual Basic clients, creating 355 Visual Basic services creating 345
W
warnings document (IData object) generation 497 flow service generation 497 IS schema generation 497 watt.server.auditLog property, described 165 watt.server.invoke.maxRetryPeriod 152 watt.server.stats.pollTime property 395 webMethods Developer main window 25 online help 42 starting 23 toolbar 30 webMethods Integration Server access requirements for 22 closing a session 39 connecting to 23, 39 disconnecting from 39 logging on to 23 notification of shutdown 40 opening a session 39 performing ACL checking 115 supported data types 430 webMethods Monitor 157, 162
521
Index
webMethods Type Library 351, 355, 358 When to include input pipeline options, described 160 When to log options, described 158 whiteSpace constraining facet 474 win32.COM.dispatch:createObject 346 windows layout 25 zooming 37 WmPublic package, definition of 174
X
XML documents and $xmldata 367 converting to IData objects 366 creating documents (IData objects) from 250 creating IS document types from 252 creating IS schemas from 245 passing to a service 366 posting via HTTP 369 testing services with 299 XML Namespace property, described 266 XML Schema definitions creating documents (IData objects) from 250 creating IS document types from 252 creating IS schemas from 245 import mechanism 247 include mechanism 247 IS schema generation warnings 497 recursive complex types 256 redefine mechanism 247 referenced by other XML Schemas 247 XML validation content constraints 240 creating IS schemas 245 definition of 282 errors 478 exceptions 492 IS schemas, overview 240 performing 282 structural constraints 240
Z
zooming in a window 37 in on transformers 235
522

8-0-SP1 Developer Users Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

8-0-SP1 Developer Users Guide

Hochgeladen von

Copyright:

Verfügbare Formate

TitlePage

Developing Integration Services

Copyright & Docu mentID

Document ID: DEV-UG-80SP1-20091204

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

About This Guide

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

About This Guide

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

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

About This Guide

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

About This Guide

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

Getting Started with Developer

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Before You Use Developer

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Specify... Note: Theserverisinstalledwithadefaultuseraccountcalled Developerthathasdeveloperprivileges.

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

Uses secure connection

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

What Does the Developer Window Contain?

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

1 Getting Started with Developer

The Navigation Panel

Navigation Panel Icons

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

Note: OtherinstalledwebMethodscomponentsmightaddelementstotheNavigation panelthatarenotdescribedintheprecedingtable.Forinformationaboutthese elements,refertothedocumentationprovidedwiththeseinstalledcomponents.

Refreshing the Contents of the Navigation Panel

The UDDI Registry Tab

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

UDDI Registry Tab Icons

Developing Integration Solutions: webMethods Developer Users Guide Version 8.0

1 Getting Started with Developer

The Recent Elements Tab