Professional Documents
Culture Documents
webMethods Developer
User’s Guide
Version 7.1.1
January 2008
webMethods
Copyright
& Docu‐
ment ID
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
General Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Files for the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Files Containing the Code that Invokes the Service . . . . . . . . . . . . . . . . . . . . . . . 339
File Containing the Code that Interacts with webMethods Integration Server . . . . 339
Building an Excel Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Files that Are Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Building a Browser-Based Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Invoking Services with a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Using the HTTP GET Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Using the HTTP POST Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Input to the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Output from the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
This guide describes how to create services using webMethods Developer. It contains
information for developers who want to build services using the webMethods flow
language or a programming language such as Java, C/C++, or Visual Basic.
To use this guide effectively, you should know how to program in Java, C/C++, and/or
Visual Basic if you will be creating services in those languages.
Document Conventions
Convention Description
Bold Identifies elements on a screen.
Italic Identifies variable information that you must supply or change based
on your specific situation or environment. Identifies terms the first
time they are defined in text. Also identifies service input and output
variables.
Narrow font Identifies storage locations for services on the webMethods
Integration Server using the convention folder.subfolder:service.
Typewriter Identifies characters and values that you must type exactly or
font messages that the system displays on the console.
UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously
are joined with the “+” symbol.
\ Directory paths use the “\” directory delimiter unless the subject is
UNIX‐specific.
[ ] Optional keywords or values are enclosed in [ ]. Do not type the [ ]
symbols in your own code.
Additional Information
The webMethods Advantage Web site at http://advantage.webmethods.com provides
you with important sources of information about webMethods products:
Troubleshooting Information. The webMethods Knowledge Base provides
troubleshooting information for many webMethods products.
Documentation Feedback. To provide feedback on webMethods documentation, go to
the Documentation Feedback Form on the webMethods Bookshelf.
Additional Documentation. Starting with 7.0, you have the option of downloading the
documentation during product installation to a single directory called
“_documentation,” located by default under the webMethods installation directory.
In addition, you can find documentation for all webMethods products on the
webMethods Bookshelf.
What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
What Does the Developer Window Contain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Working in the Developer Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Opening, Closing, and Restoring Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Changing Your Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
What Is Developer?
webMethods Developer is a graphical development tool that you use to build, edit, and
test integration logic. It provides an integrated development environment in which you
can develop the logic and supporting objects (referred to as elements) of an integration
solution. It also provides tools for testing and debugging the solutions you create.
Developer lets you rapidly construct integration logic with an easy‐to‐use
implementation language called the webMethods flow language. Flow language provides a
set of simple but powerful constructs that you use to specify a sequence of actions (steps)
that the Integration Server will execute at run time. Developer also has extensive data
transformation and mapping capabilities that allow you to quickly drag‐and‐drop data
fields from one step to the next.
Besides providing tools for constructing flow services, Developer provides additional
editors and tools for creating various elements that support the execution of an
integration solution. For example, you use Developer to create the document types and
schemas used for data validation and to define Broker/local trigger that launch the
execution of services when certain documents are published.
Developer enables you to lock an element you are working with. When you lock an
element, the element is read‐only to all other users on the Integration Server. Another
user cannot edit the element until you unlock it. Developer can also be configured to
interact with a third‐part version control system (VCS) repository; in this case, elements
are locked and unlocked as you check them out of and in to the VCS repository.
All references in this guide to locking refer to local locking on the Integration Server. For
specific information about local file locking, see Chapter 4, “Locking and Unlocking
Elements”. For information on how to implement file locking with the Version Control
System Integration feature for Developer, see the webMethods Version Control System
Integration Developer’s Guide in the webMethods_directory\_documentation directory.
Starting Developer
Use the following procedure to start Developer on your workstation. Before you start
Developer make sure that the Integration Server with which you want to use Developer is
running. You cannot work with Developer if the server is not running.
Important! You can only connect webMethods Developer version 7.1 to a webMethods
Integration Server version 7.1.
To start Developer
1 On the Start menu, click Programs, and then click webMethods.
2 Click webMethods Developer.
3 In the Open Session dialog box, complete the following:
Note: Servers to which you have successfully logged on in the
past are listed in the Server list. You can select a server from this
list or type its name and port number.
Username The name of a valid user account on this server. (The user name
must be a member of a group belonging to the Developers ACL.)
Use the exact combination of upper‐ and lower‐case characters
with which it was originally defined. IS user names are case
sensitive.
Note: The server is installed with a default user account called
“Developer” that has developer privileges.
Password The password for the user account in Username. Use the exact
combination of upper‐ and lower‐case characters with which it
was originally defined. IS passwords are case sensitive.
Note: The default password for the Developer user account is
isdev.
4 Click OK.
Tip! When you run Developer from the command line, Developer writes messages to
the console. The amount and type of information that is written is determined by the
debug level under which Developer is operating. The default debug level is 4. If you
want more detail written to the console, set the debug level to 10. You can change the
debug level by editing the ini.cnf file located in Developer_directory\config.
Note: When you start Developer, it verifies that the other webMethods components
support the same locale as Developer. If the locale of an add‐in component is not
supported by the Developer locale, Developer displays a message in the console
warning you of the locale mismatch. For example, if you start Developer in an English
locale with a localized Japanese add‐in component, Developer displays the following
message in the console:
Warning: The following plug-ins are running localized versions even though
Developer is not: ComponentName; VersionNumber.
Developer will display some text in English and the component’s text in Japanese.
A C service. A C service is a service written in C/C++.
A specification. A specification is a formal description of a service’s inputs
and outputs.
A Broker/local trigger. A Broker/local trigger is trigger that subscribes to and
processes documents published/delivered locally or to the Broker.
For more information about creating Broker/local triggers, see the Publish‐
Subscribe Developer’s Guide.
A JMS trigger. A JMS trigger is a trigger that receives messages from a
destination (queue or topic) on a JMS provider and then processes those
messages.
For more information about creating JMS triggers, see the webMethods
Integration Server JMS Client Developer’s Guide.
An IS document type. An IS document type contains a set of fields used to
define the structure and type of data in a document.
A publishable document type. A publishable document type is an IS
document type with specific publishing properties. Instances of
publishable document types can be published and subscribed to.
Publishable document types can be used anywhere an IS document type
is needed.
A publishable document type for an adapter notification. An adapter notification
can have an associated publishable document type that the adapter uses
to send the notification data to an Integration Server or a Broker.
Note: Other installed webMethods components might add elements to the Navigation
panel that are not described in the preceding table. For information about these
elements, refer to the documentation provided with these installed components.
Note: Refreshing the session is different from restoring a session. Restoring a session
allows you to save changes to an element you were working with when the
Integration Server shuts down unexpectedly. For more information about restoring
sessions, see “Restoring a Session on a Server” on page 36.
Note: When you select a Web service in the UDDI Registry tab, the editor (the middle
area of the Developer window between the Navigation panel and the Properties
panel) is blank. This is because Developer cannot modify a Web service published to a
UDDI Registry.
Use this
button... To...
Connect to a UDDI Registry while working in Developer.
Disconnect from a UDDI Registry while working in Developer.
Refresh the display of Web services. Equivalent to SessionRefresh UDDI
Registry Display.
Create an expression that filters the contents of the UDDI Registry tab
based on the value of a Web service property.
Remove the filter from the contents of the UDDI Registry tab and
display all the published Web services.
Create a Web service descriptor (WSD) from the Web service selected in
the UDDI Registry tab.
The UDDI Registry tab also contains icons to represent the UDDI Registry, the registered
business entities, and the Web services that have been published to the UDDI Registry.
The following table identifies these icons.
Tip! To view a tool tip containing the fully qualified name of the element, the package
in which the element resides, and the host name and port number of the server, rest
the mouse pointer on the element name.
You can clear the list of elements currently displayed in the Recent Elements tab by
clicking Clear.
Developer handles changes to the Recent Elements list as follows:
When you close an open element in the editor, Developer adds the element to the top
of the Recent Elements list.
Developer remembers the contents of the Recent Elements tab between sessions. If
you attempt to open an element that was deleted after you clos*ed your previous
Developer session, Developer alerts you that the element cannot be found and then
removes the element from the list.
If you attempt to open an element listed in the Recent Elements tab that another user
has deleted, moved, or renamed during your Developer session, Developer displays a
message alerting you that the element cannot be found.
If you move or rename an element during your current session, Developer
automatically refreshes the Recent Elements tab to reflect the change. If you delete an
element, Developer removes the element from the Recent Elements list.
For more information about selecting elements in the Recent Elements tab to view or edit
in the editor, see “Opening and Closing Elements in the Editor” on page 45.
The Editor
The editor contains the controls that you use to examine and edit an element you open
from the Navigation panel or Recent Elements tab. The contents of the editor vary
depending on the type of element you select.
For some element types, the editor is divided into multiple areas, including tabs
containing additional editing controls for the element. You switch among areas within
the editor just as you would between the Navigation panel or Recent Elements tab and
the editor. To select a different area, click any white space in that area. To display the
contents of a tab, click the tab name.
As mentioned earlier, you can use the Navigation panel and Recent Elements tab to select
one or more elements to view or edit in the editor. It is helpful to display multiple
elements in the editor when you are editing an element and you would like to refer back
to another element for information. For example, if you are creating or editing a
Broker/local trigger, you may want to quickly view the document types and services
associated with that trigger.
Each element you open has its own tab in the editor. The element’s title bar contains the
fully qualified name of the element and icons to indicate the element’s type and lock
status. For more information about these icons, see “Navigation Panel Icons” on page 22
and “What Is a Lock?” on page 88.
Tip! You can press CTRL+ALT+RIGHT ARROW to toggle forward between open
elements in the editor and CTRL+ALT+LEFT ARROW to toggle backward.
Tip! You can locate the active element in the Navigation panel by using the
EditLocate in Navigation command.
Tip! If the Properties panel displays the properties for an item (for example, a
document field) and you want to display the properties for its parent element (for
example, the document type to which the field belongs), click the title bar of the
parent element in the editor, the tab of the parent element in the editor, or the white
space within the editor.
Properties panel
Drag to resize the Property
and Value columns.
Depending on the type of property you select, you edit a property by:
Typing a value in the box to the right of the property name (for example, to specify
the namespace and local names that make up the universal name for a service)
Tip! You can also paste text into the box that you previously copied to the
clipboard.
Note: Developer accepts the text you type in a property box when you move the
focus outside of the box or press ENTER. You can cancel your edits before you
perform either of these actions by pressing ESC.
Selecting a value from a list (for example, to specify a validation processing rule)
Clicking a button next to the property name and supplying values on a dialog box
(for example, to specify an index when linking to or from an array variable)
Clicking the browse button to locate an element (for example, a service)
The tips area beneath the list of properties includes a description of the selected property
and its values. To obtain this information for a particular property, click the property
name.
Note: If you do not own the lock for an element, the element’s properties are read only.
Results panel
Click a variable
name...
For more information about service execution results, see Chapter 11, “Testing and
Debugging Services”.
Performing Actions
Before you can perform an action on an element, you must select the element in one of the
following ways:
Single‐click the title bar of an element in the editor.
Right‐click an element.
Single‐click one or more elements in the Navigation panel.
Tip! To select a group of adjacent elements simultaneously, press the SHIFT key as
you click. To select a group of non‐adjacent elements, press the CTRL key.
Note: Single‐clicking an element in the Navigation panel selects (highlights) the
element but does not open the element for viewing or editing in the editor. To
open an element in the editor, double‐click it.
The actions that are available for an element depend on which area of the Developer
window has the focus. For example, to run a service, the service must be open in the
editor and have the focus.
There are a number of ways to perform an action on an element after you select it:
Menu commands. You can select a command from the menu bar to perform an action on
an element. For example, to save changes to an opened element using the menu bar,
select the element in the editor and then click FileSave.
You can also access menu commands on a shortcut menu by right‐clicking the
element. For example, to open an element using a shortcut menu, right‐click the
element in the Navigation panel and then click Open. To close an editor using a
shortcut menu, right‐click the editor title bar and then click Close Active Editor.
Toolbar buttons. You can click a toolbar button to perform an action on an element. For
example, to save changes to an opened element using a toolbar button, select the
element in the editor and then click .
The toolbar buttons that are available for you to use depend on the item in the
Developer window that currently has the focus. For example, when you are editing a
flow service, the flow service toolbar buttons in the editor are not available unless the
editor has the focus.
Keys. You can use the keyboard to access a menu by pressing the ALT key plus the
underlined letter in the menu name. You can then select a command on that menu by
pressing the underlined letter in the command’s title. For example, to save changes to
an element using the keyboard, select the element, press ALT and F to access the File
menu, and then press S to save the element.
Some commands also have shortcuts assigned to them. These shortcuts are displayed
to the right of their associated commands on the menu bar. For example, to save
changes to an element using a keyboard shortcut, select that element and then press
CTRL and S.
Drag-and-drop action. You can select an element and move it to another package or
element, either on the same server or on a different server, by dragging it. For
example, to move an IS document type from one folder to another, you would drag
that document type to the new folder.
Note: Some elements, such as adapter notifications, cannot be moved using the
drag‐and‐drop action.
Most of the procedures in this guide instruct you to perform actions using menu
commands.
To... Do this...
Hide the Navigation panel,
UDDI Registry tab, and
Recent Elements tab Click along the left edge of the Developer window.
Show the Navigation
panel, UDDI Registry tab,
and Recent Elements tab
Click along the left edge of the Developer window.
Hide the Properties and
Results panels
Click along the right edge of the Developer window.
Show the Properties and
Results panels
Click along the right edge of the Developer window.
Expand or collapse editor Click on the border between the top of the editor and
details the specialized tabs beneath it.
Switching Perspectives
You can quickly change the Developer window to tailor it to the task you are performing
(for example, show only the editor and Results panel when you are testing a service) by
displaying a particular perspective. Perspectives allocate more space on the Developer
window for a particular task by hiding or minimizing the areas that are not essential to
that task.
Developer offers three perspectives:
Edit perspective. The edit perspective displays all of the Developer window areas but
minimizes the Results panel. This perspective is useful when you are opening and
editing elements and their properties.
Test perspective. The test perspective hides the Navigation panel, UDDI Registry tab,
and Recent Elements tab and maximizes the editor and the Results panel. This
perspective is useful when you are testing and debugging a service and you want to
view the results of the service’s execution, its inputs and outputs, and its pipeline
variables.
Details perspective. The details perspective hides the Navigation panel, UDDI Registry
tab, and Recent Elements tab and minimizes the Results panel. This perspective is
useful when you want to see as much of an element’s detail as possible (for example, a
service’s pipeline).
You display a perspective as follows:
You can manually adjust areas within a perspective using the other techniques described
in this section. Developer saves your settings across sessions.
If you have adjusted the perspectives manually and you want to revert them to their
default settings, use the WindowReset Perspectives command.
1 On the Session menu, click Open.
2 Complete the Open Session dialog box. For more information about completing this
dialog box, see “To start Developer” on page 19.
3 Click OK.
Important! While you have an open session on a server through Developer, you are
using a licensed seat for that server. At times when you are not actively using
Developer, you may want to close your session to free a seat on the server for others
to use.
1 Save any work that you want to keep.
2 On the Session menu, click Close.
Important! If a server shuts down and you close your session (that is, disconnect from
the server), close unsaved elements on that server in the editor, or exit Developer
before the server restarts, Developer warns you that if you continue you will lose all
unsaved work. If you do not want to lose your work, click Cancel and wait for the
connection to that server to be restored.
On the Session menu, click Restore.
Note: Restoring a session is different from refreshing the session. Refreshing the
session updates your screen to reflect the actions of other users on elements that are
displayed within the Navigation panel and the editors. A refresh action does not
restore the working state of an element if a server shuts down. For more information
about refreshing the Navigation panel, see “Refreshing the Contents of the
Navigation Panel” on page 25.
If you did not save your work before shut down occurred, you might be able to restore
your session when the server restarts and then save your work. For more information
about restoring sessions, see “Restoring a Session on a Server” on page 36.
Important! If you are outside of the corporate firewall, do not change your password
unless you use SSL to open the session on the webMethods Integration Server. If you
do not use SSL, your password can be exposed in unencrypted form.
Note: You cannot use Developer to change passwords that are stored in an LDAP
server.
Password Requirements
For security purposes, webMethods Integration Server places length and character
restrictions on passwords. webMethods Integration Server contains a default set of
password requirements; however, your server administrator can change these. For more
information about these password requirements, contact your server administrator.
The default password requirements provided by webMethods are as follows:
Requirement Default
Minimum length 8
Minimum number of alphabetic characters 3
Minimum number of uppercase characters 2
Minimum number of lowercase characters 2
Minimum number of numeric characters 1
Minimum number of special characters (non‐alphabetic and non‐numeric 1
characters, such as *. ?, &)
To ensure the security of your password, follow the additional guidelines below:
Do not choose obvious passwords, such as your name, address, phone number,
license plate, spouse’s name, child’s name, or a birthday.
Do not use any word that can be found in the dictionary.
Do not write your password down.
Do not share your password with anyone.
Change your password frequently.
1 On the Session menu, click Change Password.
2 In the Change Password dialog box, in the Old Password field, type your current
password.
3 In the New Password field, type your new password.
4 In the Confirm New Password field, retype your new password. Click OK.
Important! The server administrator can disable the feature for changing your
password from Developer. If the feature is disabled and you try to change your
password, you will receive a message stating that the administrator has disabled the
feature.
On the Developer window toolbar, click .
Properties. For help about a property, click the property in the Properties panel.
Developer displays a description of the property at the bottom of the Properties
panel.
Built-in services. For a description of a built‐in service within the WmART, WmDB,
WmPKI, WmPRT, or WmPublic packages, do one of the following:
If you are browsing the services within a package in the Navigation panel, select a
service and press F1.
If you have added a built‐in service to a flow service using an INVOKE step, select
the built‐in service in the editor and press F1.
If you are browsing for a built‐in service to add to a flow service, select the built‐in
service in the Select dialog box and press F1.
You can also view or print descriptions of all built‐in services from one location by
clicking HelpBuilt-In Service Reference.
What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Creating New Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Specifying Dependency Checking Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Notes About Performing Actions on Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Opening and Closing Elements in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Moving and Copying Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Saving Changes to Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Finding Elements and Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Finding Dependents and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Inspecting Pipeline References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
What Is an Element?
An element is an item that exists in the Navigation panel in webMethods Developer.
Elements include folders, services, specifications, IS document types, triggers, and IS
schemas. In the Navigation panel, servers and packages are not considered to be
elements.
Folders, services,
triggers,
specifications,
IS document types,
and IS schemas are
elements.
The following table identifies where to go for more information about creating new
elements and performing actions on those elements.
1 On the File menu, click New.
2 On the New dialog box, click the type of element you want to create and then click
Next.
3 Follow the prompts given by Developer for the type of element you are creating.
When you have supplied all of the information that Developer needs to create the
element, the Finish button becomes active.
4 Click Finish.
If you select multiple elements and then click this button, Developer offers only the All
Choices option, which opens the New dialog box described in the procedure above.
Note: Developer ensures that the fully qualified name of each element within the
server is unique. Depending on the action you are performing on the element,
Developer accomplishes this either by alerting you that the action cannot be
completed or by appending a number to the name of the element after the action is
performed. For example, if you are copying a flow service named checkOrder2 to a
destination that already contains a flow service with that name, Developer copies the
service and names the copy checkOrder2_1.
? ' - # = ) ( . / \ ;
& @ ^ ! | } { ` > <
% * : $ ] [ " + , ~
Characters outside of the basic ASCII character set, such as multi‐byte characters
If you specify a name that disregards these restrictions, Developer displays an error
message. When this happens, use a different name or try adding a letter or number to the
name to make it valid.
Editing Elements
To edit an element, you must first lock it. You must also have Write access to the element.
For more information about locking and unlocking elements, see Chapter 4, “Locking
and Unlocking Elements”. For more information about access permissions, see Chapter 5,
“Assigning and Managing Permissions”.
If you have enabled the VCS Integration feature, you must first check out the element
before you can edit it. For more information, see the webMethods Version Control System
Integration Developer’s Guide in the webMethods_directory\_documentation directory.
Tip! You can produce printable versions of many of the elements in the Navigation
panel by clicking FileView as HTML.
Note: The dependency checking options are enabled by default.
1 On the Tools menu, click Options.
2 Click General. Under Navigation Panel, do the following:
Select... To...
Select... To...
3 Click OK.
For more information about finding dependents, see “Finding Dependents and
References” on page 60.
from selecting multiple elements when doing so could cause confusion or undefined
results. For example, you cannot select a server and any other element, a package and
any other element, or a folder and one or more elements contained within that folder.
If you select multiple elements and Developer encounters an error while performing
the specified action on one or more of the elements, Developer displays a dialog box
listing the elements for which the action failed. You can obtain more information
about why the action failed by clicking Details.
The elements you want to move, copy, rename, save, or delete must be unlocked, or
locked by you. For more information about locking and unlocking elements, see
Chapter 4, “Locking and Unlocking Elements”.
You cannot undo a move, copy, rename, or delete action using the EditUndo
command.
If you select a publishable document type that is associated with an adapter
notification, Developer handles actions performed on the document type as follows:
For non‐copy actions, you must also select the adapter notification before you can
perform a non‐copy action on the document type.
For copy actions, you can select the publishable document type without selecting
its associated adapter notification. However, the copied publishable document
type loses its association with the adapter notification.
1 Select one or more elements to open.
Tip! Press the SHIFT key as you click to select a group of adjacent elements. Press
the CTRL key to select a group of non‐adjacent elements.
2 On the File menu, click Open.
If you are opening an element from the Recent Elements tab and the element resides
on a server to which you are no longer connected, Developer prompts you to log on to
that server before displaying the element.
Do one of the following:
To... Do this...
Note: You do not need to close elements when you exit Developer. Developer
remembers which elements were open and displays them when you restart
Developer. If you close an element without saving changes made to the element,
Developer will prompt you to save changes.
General
You must have Read access to the elements you are moving or copying and Write
access to the packages, folders, or servers to where you want to move/copy them. For
more information about Write access and ACLs assigned to elements, see Chapter 5,
“Assigning and Managing Permissions”.
When you move or copy an element, Developer automatically changes the element’s
fully qualified name to reflect its new location.
You cannot move an element to a location that already contains an element with the
same name. If you copy the element, however, Developer copies the element and
appends a number to the end of the name of the copied element.
You cannot move multiple elements with the same name to a single location.
After you move or copy an element, the element becomes locked by you.
When you copy multiple elements to another location on the same server and the
elements contain references to each other, Developer updates the references if you
have selected Update local reference(s) when pasting multiple elements on the Options
dialog box. For example, if you copy a folder that contains two services and one of the
services invokes the other, Developer will update the reference to the invoked service.
You cannot move or copy a Java service to a folder that contains other Java services
that are system locked or locked by another user. If you attempt to do so, Developer
cancels the entire move/copy action.
When you move or copy a Java service, Developer will also move or copy the service’s
Shared fields to the destination folder, unless the destination folder already contains
Shared fields with different values. In this case, you must first manually copy the
Shared fields into the destination folder and then move or copy the Java service.
Tip! To retain the status of a publishable document type and its link to a Broker
document type, use the package replication functionality in the Integration Server
Administrator instead of using Developer to move or copy the package
containing the publishable document type. For information about package
replication, see the webMethods Integration Server Administrator’s Guide.
1 Select the elements that you want to move or copy.
2 Do one of the following:
To... Click...
Cut the element EditCut
Copy the element EditCopy
Tip! You can cancel a cut action by pressing ESC.
3 If the elements you want to move or copy contain unsaved changes, Developer alerts
you that you must first save the changes. Click OK to close the alert dialog box. Then,
save the changes and repeat the move/copy action.
4 If you do not have Read access to the elements you are moving or copying, or Write
access to the location you are moving/copying them to, Developer displays a message
that identifies the elements that are preventing the action from completing
successfully. Click OK and then either obtain the proper access from your system
administrator or select only those elements to which you have proper access.
5 Select the location where you want to move or copy the elements.
6 On the Edit menu, click PasteAfter.
7 If the destination already contains an element with the same name as an element you
are moving or copying, do one of the following:
If you are moving the element, Developer alerts you that the element cannot be
moved. Click OK to close the alert dialog box. Rename the element if desired and
repeat the move action.
If you are copying the element, Developer copies the element and appends a
number to the name of the copied element. (For example, if you are copying a
flow service named checkOrder2 to a destination that already contains a flow
service with that name, Developer copies the service and names the copy
checkOrder2_1.) Rename the element if desired.
For more information about renaming elements, see “Renaming Elements” on
page 51.
8 If one of the elements you moved or copied is a Java service, perform the following as
necessary:
If you are moving or copying the Java service to a folder with other Java services
that are system locked or locked by another user, Developer alerts you that the
element cannot be moved/copied.
Click OK and then ask the owner of the lock to remove the lock.
If the Java service you are moving or copying contains a shared source that
conflicts with the shared source of an existing Java service in the destination
folder, Developer alerts you that there is a conflict. Click OK to use the destination
folder’s shared source, or click Cancel to cancel the entire move action.
Note: If no shared Java source conflict exists, Developer moves the Java service
and its shared source to the destination folder. If a conflict does exist, you
must re‐specify the Shared tab information in the copy of the service. (You can
copy the information from the Shared tab for the original service to the Shared
tab for the copy of the service.)
For more information about dependency safeguards, see “Specifying Dependency
Checking Safeguards” on page 43.
Tip! You can also move elements by clicking and dragging them to their new location.
Renaming Elements
When renaming elements, keep the following points in mind:
You can rename any elements for which you have Write access to the element and its
parent folder. When renaming a folder, you must also have Write access to all
elements within the folder. For more information about Write access and ACLs
assigned to elements, see Chapter 5, “Assigning and Managing Permissions”.
When you rename a folder, Developer automatically renames all of the elements in
that folder (that is, changes their fully qualified names).
If the folder you want to rename contains elements with unsaved changes, you must
save the changes before you can rename the folder.
Element names must be unique across all packages. If you try to rename an element
using a name that already exists at that level in any package, Developer reverts the
element back to its original name.
When you rename an adapter notification, Developer also renames its associated
publishable document type and prompts you to indicate whether to rename the
associated Broker document type.
You cannot rename a listener or connection element.
To rename an element
1 Select the element that you want to rename.
2 On the Edit menu, click Rename.
3 If the element you want to rename contains unsaved changes, Developer alerts you
that the element cannot be renamed until you save the changes. Click OK to close the
alert dialog box. Then, save the changes and repeat the rename action.
4 Developer moves the cursor to the end of the element name. Edit the name and press
ENTER.
If an element already exists with that name at the same level, Developer displays a
message alerting you that the rename action could not be completed. Click OK to close
the message dialog box and repeat the rename action.
Tip! You can cancel a rename action by pressing ESC.
To... Click...
For more information about dependency safeguards, see “Specifying Dependency
Checking Safeguards” on page 43.
Do one of the following:
To... Do this...
If you attempt to close Developer, close your session on the current server, close an
unsaved element in the editor, or perform an action on an element without saving your
changes, Developer will prompt you to save changes first.
Deleting Elements
When deleting elements, keep the following points in mind:
You can delete any elements to which you have Write access for the element and its
parent folder. When deleting a folder, you must also have Write access to all elements
within the folder. For more information about Write access and ACLs assigned to
elements, see Chapter 5, “Assigning and Managing Permissions”.
When you delete a folder or the last Java service in a folder, Developer also deletes the
shared source for that folder. If you cancel the delete action, no elements (including
non‐Java service elements) are deleted.
You can only delete an adapter notification’s publishable document type if you delete
its associated adapter notification.
When you delete an adapter notification, Developer also deletes its associated
publishable document type and prompts you to indicate whether to delete the
associated Broker document type.
You cannot delete a listener or connection element.
To delete elements
1 Select the elements that you want to delete.
2 On the Edit menu, click Delete.
3 If you selected the Confirm before deleting check box in the Options dialog box, do the
following:
a If any elements on the server contain unsaved changes, Developer prompts you to
save the element(s). Do one of the following:
To... Click...
b If the elements you are deleting are not dependents of other elements, Developer
prompts you to confirm the delete action. Click OK.
c If the elements you are deleting are dependents of other elements, Developer
alerts you to the elements that will be affected by the deletion. Do the following:
1 If one of the elements you want to delete is a publishable document type or an
adapter notification, do one of the following:
To... Do this...
Important! If you delete a publishable document type and Broker document
type associated with a trigger or a flow service, you might break any
integration solution that uses the document type.
If you delete the Broker document type, you might negatively impact any
publishable document types created from that Broker document type on other
Integration Servers. When the developers synchronize document types with
the Broker and they choose to Pull from Broker, publishable document types
associated with the deleted Broker document type will be removed from their
Integration Servers.
2 Continue or cancel the delete action as follows:
To... Click...
Delete the elements from the Navigation panel (and Continue
therefore break any links to dependent elements)
Cancel the entire delete action Cancel
For more information about dependency safeguards, see “Specifying Dependency
Checking Safeguards” on page 43.
named “Test,” “MyTest,” and “TestFinal.” You can also include regular expression
operator characters. For example:
To find... Type...
All elements containing “PO” PO
All elements starting with “PO” ^PO
All elements ending with “PO” PO$
All services with the exact name of “logPO” :logPO$
All elements containing “log” followed by any two characters (wildcards) log..
For a complete list of regular expression operator characters, see Appendix B, “Regular
Expressions”.
1 Click anywhere in the Navigation panel.
2 On the Edit menu, click Find. Developer displays the Find In Navigation Panel dialog
box.
3 In the Find In Navigation Panel box, type any portion of the fully qualified name of the
element that you want to find.
4 If you want to limit the scope of the search to a specific package, select the package in
the Package list.
5 Click Find. The Find In Navigation Panel dialog box displays the results of the search.
...the names of 33
elements in the
Navigation panel.
All of these
elements contain
“PO” in their fully
qualified name.
6 To jump to an element in the Navigation panel, select that element in the results and
click Go To.
Note: If you receive a “Couldn’t find in Navigation panel” message when you click Go
To, you probably do not have List access to the element. Contact your server
administrator to obtain access.
Tip! For an active element in the editor, you can highlight the element’s location in the
Navigation panel using the EditLocate in Navigation command.
Developer searches the tree as follows:
If you select a field, Developer begins searching at the selected field and continues
to the bottom of the tree. If you have not selected a field, Developer begins
searching at the top of the tree.
When Developer finds a field that matches the search criteria, Developer selects
the field in the tree.
When Developer reaches the bottom of the tree, Developer displays a message
asking if you would like to continue searching from the top of the tree.
After completing a search of the entire tree, if Developer cannot find a matching
field, Developer displays a message stating that the search text was not found.
1 Select the tree in which you want to search for a field.
2 On the Edit menu, click Find.
3 In the Find what field, type the text you want to search for. If you want to search for a
parent‐child field combination, use a forward slash (/) to separate the parent field
from the child field.
4 To further refine your search, do one or more of the following:
To... Do this...
5 Click Find Next. If Developer finds a match, it selects the field and displays it on the
Pipeline tab.
6 Click Find Next to find the next field that matches the search criteria.
1 In the editor, select the INVOKE step containing the service you want to locate.
2 On the Edit menu, click Locate in Navigation. Developer locates and selects the service in
the Navigation panel.
Finding Dependents
To determine how a selected element is used by other elements on the server, you can
find dependents of the selected element. For example, suppose that the flow service
ServiceA invokes the flow service receivePO. The ServiceA service uses (that is, is a dependent
of) the receivePO service. If you delete receivePO from the Navigation panel, ServiceA will
not run.
Dependent elements
This service is a
dependent of...
...each of these
services.
During debugging, you might want to locate all of the dependents of a given service or IS
document type. Or, before editing an IS document type, you might want to know what
elements, such as specifications, Broker/local triggers, or flow services, will be affected by
changes to the IS document type. Use the Find Dependents command to find all the
dependents.
Note: Developer does not consider a Java service that invokes another services to be a
dependent. For example, if Java service A invokes service B, and you instruct
Developer to find dependents of service B, service A will not appear as a dependent.
1 In the Navigation panel or in the editor, select the element for which you want to find
dependents.
2 On the Tools menu, click Find Dependents.
The Find Dependents dialog box displays the dependents of the element.
...this element.
3 After Developer finds the dependents of the selected element, you may do any of the
following:
To jump to an element in the Navigation panel, select that element in the results
and then click Go To.
To see all dependents of a found dependent, click next to the item in the results
list.
To limit the scope of the search to a specific package, select the package in the
Package list and then click Find.
Finding References
To determine how a selected element uses other elements on the server, you can find
references of the selected element. For example, the flow service ServiceA invokes the
services receivePO, pub.schema:validate, processPO and submitPO. Additionally, in its input
signature, ServiceA declares a document reference to the IS document type PODocument.
The services receivePO, validate, processPO, and submitPO, and the IS document type
PODocument, are used by (that is, they are references of) ServiceA.
Elements as references
Each of these
services is a
reference of
ServiceA.
During debugging of a complex flow service, you might want to locate all of the services,
IS document types, and specifications used by the flow service. Use the Find References
command to locate the references.
You can also use the Find References command to locate any unresolved references. An
unresolved reference is an element that does not exist in the Navigation panel yet is still
referred to in the service, IS document type, or specification that you selected. The
element might have been renamed, moved, or deleted. To prevent unresolved references,
specify the dependency checking safeguards. For more information about these
safeguards, see “Specifying Dependency Checking Safeguards” on page 43.
Note: Developer does not consider document references to schema types to be
references, nor does it consider services invoked within a Java service to be references
of the Java service. For example, if Java service A invokes service B, and you instruct
Developer to find references for service A, service B will not appear as a reference of A.
1 In the Navigation panel or in the editor, select the element for which you want to find
references.
2 On the Tools menu, click Find References.
The Find References dialog box displays the references of the element. Unresolved
references are indicated in bold italics.
...these elements.
3 After Developer finds the references of the selected element, you may do either of the
following:
To jump to an element in the Navigation panel, select that element in the results
and then click Go To.
To see all references of a found reference, click next to the item in the results
list.
Pipeline reference
This variable is a
reference to the
PODocument in the
Navigation panel.
When you edit an IS document type, the changes affect any document reference and
document reference list variables defined by that IS document type. The changes might
make pipeline references invalid. For example, suppose the input signature for ServiceA
contains a document reference variable POInfo based on the IS document type
PODocument. The IS document type PODocument contains the field PONum. In the pipeline
for ServiceA, you link the PONum field to another pipeline variable. If you edit the
PODocument IS document type by deleting the PONum field, the pipeline reference (the
link) for the field in the ServiceA pipeline is broken (that is, it is invalid) because the
pipeline contains a link to a field that does not exist.
When you edit an IS document type, you might want to check all dependent pipeline
modifiers for validity. You can use the ToolsInspect Pipeline References command to
locate any broken or invalid pipeline references. You can use this command to:
Search for invalid pipeline references in a selected flow service.
Search for invalid pipeline references involving document reference and document
reference list variables defined by a selected IS document type.
When inspecting pipeline references, keep the following points in mind:
You can inspect pipeline references in a selected flow service. You can also inspect
pipeline references for document reference or document reference list variables based
on a selected IS document type. The search results include only flow services,
document reference variables, or document reference list variables that contain
invalid pipeline modifiers.
Values set at the top level of a document reference or document reference list in the
pipeline are not considered pipeline references. (That is, a Set Value modifier
assigned to the document reference is not a pipeline reference.) Therefore, if a Set
Value modifier assigned to a document reference contains input values for a
nonexistent field, it will not appear in the search results even though it is invalid.
The search results will not show data type and dimensionality mismatches. For
example, suppose that you link a String named Number to the PONum String list
within the document reference PODocument. This dimensionality mismatch will not
appear in the search results.
When you inspect pipeline references in a flow service, Developer inspects references
across all packages on webMethods Integration Server.
When you inspect pipeline references for an IS document type, you can inspect
references across a specific package or all packages.
1 In the Navigation panel or in the editor, select the flow service or IS document type
for which you want to find invalid pipeline references.
2 On the Tools menu, click Inspect Pipeline References.
The Inspect Pipeline References dialog box displays all invalid pipeline references for
the selected service or IS document type.
If you inspected a flow service, the search results contain all of the document
references that have invalid pipeline references in that flow.
If you inspected an IS document type, the search results contain all of the flow
services that have invalid pipeline references to that IS document type.
3 After Developer finds the pipeline references of the selected element, you may do any
of the following:
To jump to an element in the Navigation panel, select that element in the results
and then click Go To.
To jump to the unresolved reference in the pipeline, select the element in the
results and then click Find in Flow.
If the selected element has multiple unresolved references in the same flow
service and you want to automatically jump to the next reference within the
selected element, you can use the Find Next command. To use the Find Next
command, keep the Inspect Pipeline References dialog box open and click Edit
Find Next.
If the selected element is a document type and you want to limit the scope of the
search to a specific package, select the package in the Package list and then click
Inspect.
Caching Elements
You can improve performance in Developer by caching Navigation panel elements that
are frequently used. When elements are located in the Developer cache, Developer does
not need to request them from the Integration Server and can therefore display them
more quickly.
To cache elements
1 On the Tools menu, click Options.
2 In the Options dialog box, click General.
3 Under Navigation Panel, in the Number of elements to cache box, type the number of
elements that you want to cache per Developer session. The total number of cached
elements includes elements on all the servers to which you are connected.
The minimum number of elements is 10. The higher the number of elements, the
more likely an element will be in the cache, which reduces network traffic and speeds
up Developer.
4 Click OK. The caching settings take effect immediately.
If you enter an illegal cache size Developer displays an error and resets the cache size
to the previous value.
Note: Keep in mind that increasing the cache reduces the amount of available memory.
If you experience memory problems, consider decreasing the number of cached
elements.
1 On the Tools menu, click Options. Developer displays the Options dialog box.
2 Click General.
3 Under Navigation Panel, click the Clear Cache button. All cached elements are removed
from memory.
Note: Clearing cached elements from Developer is different from clearing the contents
of the pipeline from webMethods Integration Server cache. If you want to clear the
contents of the pipeline from a server’s cache, see “Configuring a Service’s Use of
Cache” on page 131.
What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Assigning Startup, Shutdown, and Replication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
What Is a Package?
A package is a container that is used to bundle services and related elements, such as
specifications, IS document types, IS schemas, and output templates. When you create a
folder, service, specification, IS document type, IS schema, or output template, you save it
in a package.
Packages are designed to hold all of the components of a logical unit in an integration
solution. For example, you might group all the services and files specific to a particular
marketplace in a single package. By grouping these components into a single package,
you can easily manipulate them as a unit. For example, you can copy, reload, distribute,
or delete the set of components (the “package”) with a single action.
Although you can group services using any package structure that suits your purpose,
most sites organize their packages by function or application. For example, they might
put all purchasing‐related services in a package called “PurchaseOrderMgt” and all time‐
reporting services into a package called “TimeCards.”
On the server, a package represents a subdirectory within the
IntegrationServer_directory\packages directory. All the components that belong to a
package reside in the package’s subdirectory.
Note: Every element in webMethods Developer must belong to a package.
For a list and description of packages installed with the Integration Server, see the
webMethods Integration Server Administrator’s Guide.
Package Management
You can use webMethods Developer to perform certain package management tasks, such
as creating, copying, and deleting packages, on the Integration Server. When you
perform a package management task, all of the files and services in the package are
affected.
The following table identifies all of the package management tasks that can be performed
using Developer or the Integration Server Administrator. If you can perform the task
with Developer, the See column directs you to a page within this guide for instructions.
For tasks that can only be performed using the Integration Server Administrator, the See
column directs you to the webMethods Integration Server Administrator’s Guide.
To... See...
Create a package page 72
Activate a package webMethods Integration Server
Administrator’s Guide
Copy a package to another server page 74
To... See...
View details for a package page 73
Display specific packages by filtering the webMethods Integration Server
Packages List Administrator’s Guide
Document the purpose and function of a page 76
package
View the patch history for a package page 79 and
webMethods Integration Server
Administrator’s Guide
Assign startup, shutdown, or replication page 83
services to a package
Reload the services and files in a package page 77 and
into memory without restarting the server webMethods Integration Server
Administrator’s Guide
Delete the contents of a package page 77 and
webMethods Integration Server
Administrator’s Guide
Assign a version number to a package page 78 and
webMethods Integration Server
Administrator’s Guide
Identify packages that must be loaded page 81
before a specific package is loaded (package
dependencies)
Export a package or partial package page 78
Replicate or copy the contents of a package page 74 and
and send (publish) it to other Integration webMethods Integration Server
Servers Administrator’s Guide
Disable a package without deleting the webMethods Integration Server
package Administrator’s Guide
Enable a package that you previously webMethods Integration Server
disabled Administrator’s Guide
Recover services and related files from a webMethods Integration Server
deleted package Administrator’s Guide
Archive a copy of the package (such as for a webMethods Integration Server
backup copy) Administrator’s Guide
Creating a Package
When you want to create a new grouping for services and related files, create a package.
Packages can store services, specifications, IS document types, output templates, and
schemas.
When you create a package, Developer creates a new subdirectory for the package in the
file system on the machine where the Integration Server is installed. For information
about the subdirectory and its contents, see the webMethods Integration Server
Administrator’s Guide.
To create a package
1 On the File menu, click New.
2 In the New dialog box, select Package, and then click Next.
Developer displays the New Package dialog box.
3 In the Name field, type the name for the new package using any combination of letters,
numbers, and the underscore character. Click Finish.
Developer refreshes the Navigation panel and displays the new package.
Note: Avoid using control characters and special characters like periods (.) in a
package name. The watt.server.illegalNSChars setting in the server.cnf file (which
is located in the IntegrationServer_directory\config directory) defines all the
characters that you cannot use when naming packages. Additionally, the
operating system on which you run the Integration Server might have specific
requirements that limit package names.
Tip! You can quickly create a package beneath the server you are currently working
with by clicking next to the New button on the toolbar and then clicking Package.
Type the name of the package and then click OK.
You can then create a folder beneath the package by clicking next to the New
button and then clicking Folder. Developer adds the folder beneath the package, with
a default name of Untitled.
1 Select the packages whose details you want to view.
2 On the File menu, click Open.
For more information about package details, see “Assigning a Version Number to a
Package” on page 78, “Viewing the Patch History for a Package” on page 79, and
“Identifying Package Dependencies” on page 81.
1 Open the file Developer_directory\config\developer.cnf with a text editor.
2 Add the following properties to the file:
dev.maxServerLockInfoCalls=<value>
Defines the maximum number of lock state queries that will be made from Developer
to Integration Server. The default value is 20. After this maximum is reached, cached
values are retrieved for each element. These cached values may be inaccurate, but the
only result is that menu items may be enabled or disabled incorrectly.
dev.maxLockInfoCalls=<value>
Defines the maximum number of cached lock states that are retrieved. The default
value is 100. After this maximum is reached, the last known lock state for each
remaining element is used. This state may be incorrect, but as above, the only result is
that menu items may be enabled or disabled incorrectly.
For example, when a large package is opened (using the default values): Full lock
status information will be retrieved for the first 20 elements. For elements 21‐100,
cached lock state information will be retrieved. For elements 101 and above, the last
known lock state will be used.
3 Save the file.
4 Shut down and restart Developer.
Note: The lower the values for these settings, the more the performance will improve.
Applying a value of zero (0) to these settings will eliminate all lock state queries to the
server. This may result in some temporarily out‐of‐sync lock states, but these will be
updated during normal Developer operations.
Lock state information is updated as child elements are opened in the Navigation
panel.
distributing package updates to developers working in large, collaborative
environments.
For information about replicating packages and managing releases from within
Integration Server Administrator, see the webMethods Integration Server Administrator’s
Guide.
When copying packages, keep the following points in mind.
You can copy a package to a different server only if you are a member of a group
assigned to the Replicators ACL on the source and destination servers and you are
logged on to both servers.
Before you copy a package that contains elements with unsaved changes, you must
save the changes.
You cannot undo a copy action using the EditUndo command.
You cannot copy a package to another server if the destination server already contains
a package with that name.
Note: Because UNIX directories are case sensitive, Integration Servers running in a
UNIX environment will allow packages with similar names to reside on the same
server. For example, you can copy a package named orderProcessing to a server that
contains a package named OrderProcessing.
If you copy a package that depends on other packages to load (that is, contains
package dependencies), and the required packages are not present on the destination
server, the package will be copied but it will not be enabled.
For more information about setting package dependencies, see “Identifying Package
Dependencies” on page 81.
For more information about copying elements within a package, see Chapter 2,
“Managing Elements in the Navigation Panel”.
To copy a package
1 Select the package that you want to copy.
2 On the Edit menu, click Copy.
3 If the package you want to copy contains elements with unsaved changes, Developer
alerts you that the package cannot be copied until you save the changes. Click OK to
close the alert dialog box. Then, save the changes and repeat the copy action.
4 Select the server where you want to copy the package.
5 On the Edit menu, click Paste After.
Tip! You can also copy packages by clicking them and dragging them to their new
location. Developer retains a copy of the package and its contents on the source
server.
Documenting a Package
You can communicate the purpose and function of a package and its services to other
developers by documenting the package.
1 Document the package in one or more Web documents (such as HTML pages). Be
sure to name the home page for the package documentation index.html. The
index.html file can contain links to the other Web documents for the package. An
index.html file exists for each package installed by the Integration Server.
2 Place the documents in the pub subdirectory for the package on the Integration
Server.
For example, place the package documentation for a package named
“PurchaseOrders” in the following directory:
IntegrationServer_directory\packages\PurchaseOrders\pub
Tip! An alternate location for package documentation is the
IntegrationServer_directory\packages\doc directory. Typically, this directory is
used for reference material such as PDFs that do not need to be published to the
Web.
Enter the URL for the package documentation. The URLs for package documentation
have the following format:
http://serverName:port/PackageName/DocumentName
where:
serverName:port is the name and port address of the Integration Server on which
the package resides.
PackageName is the name of the package for which you want documentation.
DocumentName is the name of the Web document you want to access. If you do
not specify a DocumentName, the Integration Server
automatically displays the index.html file.
Reloading a Package
Sometimes, you need to reload a package on the server to activate changes that have been
made to it outside of Developer. You need to reload a package if any of the following
occurs:
A Java service that was compiled using jcode is added to the package.
New jar files are added to the package.
Any of the configuration files for the package are modified.
Note: Reloading a package is not the same as refreshing the Navigation panel. When
you refresh the Navigation panel, webMethods Developer retrieves a fresh copy of
the contents of all the packages from the memory the Integration Server. When you
reload a package, the Integration Server removes the existing package information
from memory and loads new versions of the package and its contents into its
memory.
To reload a package
1 In the Navigation panel, select the package you want to reload.
2 On the File menu, click Reload Package.
Deleting a Package
When you no longer need the services and files in a package, you can delete the package.
Deleting a package removes the package and all of its contents from the Navigation
panel.
When you delete a package from Developer, the Integration Server saves a copy of the
package. If you later want to recover the package and its contents, contact your server
administrator. Only Integration Server Administrator users can recover a package. For
more information about recovering packages, see the webMethods Integration Server
Administrator’s Guide.
Before you delete a package, make sure that:
Other users or other services do not use (depend on) the services, templates, IS
document types, and schemas in the package. You can use the Find Dependents
command to identify other services that are dependent on a service in a package that
you want to delete. For more information, see “Finding Dependents and References”
on page 60.
All elements in the package that you want to delete are unlocked, or locked by you. If
the package contains elements that are locked by others or system locked, you cannot
delete the package.
To delete a package
1 In the Navigation panel, select the package you want to delete.
2 On the Edit menu, click Delete.
To export a package
1 In the Navigation panel, select the package you want to export.
2 On the File menu, click Export. Developer displays the Export To dialog box.
3 Select the location on your hard drive where you want the exported package to reside.
Click Save.
This exports the package to a ZIP file and saves it on your hard drive. The ZIP file can
then be published on another server.
To export an element
1 In the Navigation panel, select the folder or element that you want to export.
2 On the File menu, click Export. Developer displays the Export To dialog box.
3 Select the location on your hard drive where you want the exported partial package to
reside. Click Save.
This exports the folder or element to a ZIP file and saves it on your hard drive. The
ZIP file can then be unzipped into the ns directory of a package on the server.
Important! When you change the version number of a package, make sure that you
update the package dependencies for other packages that depend on the earlier
version of this package.
Tip! Assign and change package version numbers through Developer only when the
packages are in a development stage. To avoid difficulties installing package releases,
do not change version numbers on packages you receive from trading partners,
packages to which you subscribe, or packages installed with the Integration Server.
1 In the Navigation panel, select the package to which you want to assign a version
number.
2 On the File menu, click Open.
3 In the editor, click the package’s Settings tab.
4 In the Package Version field, type the version number you want to assign to the
package. Be sure to format the version number in one of the following ways: X.X or
X.X.X (for example, 1.0, 2.1, 2.1.3, or 3.1.2).
5 On the File menu, click Save to save your changes.
If the version number you entered does not use one of the formats specified in step 4,
Developer displays a message stating that the format is not correct.
Note: You can also use the Integration Server Administrator to assign version numbers
to packages. For more information, see the webMethods Integration Server
Administrator’s Guide.
Note: When the server administrator installs a full release of a package (a release that
includes all previous patches for the package), the Integration Server removes the
existing patch history. This helps the server administrator avoid potential confusion
about version numbers and re‐establish a baseline for package version numbers.
1 In the Navigation panel, select the package for which you want to view a patch
history.
2 On the File menu, click Open.
3 In the editor, click the package’s Settings tab and review the fields under Patch history.
Name The name of the package.
Version The version number of the package. A user assigns a version
number when they create a package release. By default, Developer
assigns version 1.0 to a new package.
Build The build number of the package. The build number is a generation
number that a user assigns to a package each time the package is
released. For example, a user might release version 1.0 of the
“Finance” package ten times and assign build numbers 1,2,3…10 to
the different releases or builds of the package.
The Build number is not the same as the Version number. One
version of a package might have multiple builds.
Description A brief description of the package written by the user who created
the package release.
Time The time at which the package release (patch) was created.
JVM Number The version of the JVM (Java virtual machine) required to run the
package.
Publisher The name of the publishing server that created the package release.
Patch The patch numbers included in this release of the package.
Number
Important! If you create new adapter services and adapter notifications, you should
save them in packages that identify the webMethods AdapterName package as a
package dependency.
Important! Other webMethods components might include packages that register new
types of elements in Developer. You should save instances of these new element types
in packages that list the registering package as a package dependency. The registering
package needs to load before your packages so that Developer can recognize
instances of the new element type. For example, if you create new flat file schemas,
you should save the flat file schemas in packages that identify the WmFlatFile
package as a package dependency.
1 In the Navigation panel, select the package for which you want to specify package
dependencies.
2 On the File menu, click Open.
3 In the editor, click the package’s Settings tab.
5 In the Enter Input Values dialog box, enter the following information:
Package The name of the package you want Integration Server to load before
the package selected in the Navigation panel.
Version The version number you want Integration Server to load before the
package selected in the Navigation panel.
More than one version of the same package might contain the
services and elements that a dependent package needs the
Integration Server to load first. You can use an asterisk (*) as a
wildcard in the version number to indicate that any version number
greater than or equal to the specified version will satisfy the package
dependency. For example, to specify version 3.0 or later of a
package, type 3.* for the version number. To specify versions 3.1 or
later, type 3.1.* for the version number.
If any version of the package satisfies the package dependency, type
*.* as the version number.
6 Click OK.
7 On the File menu, click Save.
Important! Only one version of a package can be installed at one time. If the available
version of the package specified in the package dependency is not the correct version,
the Integration Server does not load the dependent package. The Integration Server
writes a dependency load error for the dependent package to the server log.
Important! Make sure that you do not create circular package dependencies. For
example, if you identify “FinanceUtil” as a dependent package for the “Finance”
package, do not identify “Finance” as a dependent package for the “FinanceUtil”
package. If you create circular package dependencies, neither package will load the
next time you start the Integration Server.
1 In the Navigation panel, select the package for which you want to remove a package
dependency.
2 On the File menu, click Open.
3 In the editor, click the package’s Settings tab.
4 Under Package Dependencies, select the package dependency you want to remove.
5 Click .
6 On the File menu, click Save.
Startup services are useful for generating initialization files or assessing and preparing
(for example, setting up or cleaning up) the environment before the server loads a
package. However, you can use a startup service for any purpose.
Tip! If a startup service invokes a service in another package, make sure to identify the
other package as a package dependency for the package containing the startup
service.
Note: The term replication service does not refer to the services contained in
pub.replicator or to services that subscribe to replication events (replication event
services).
1 In the Navigation panel, select the package to which you want to assign startup,
shutdown, or replication services.
2 On the File menu, click Open.
3 In the editor, click the package’s Startup/Shutdown/Replication Services tab.
4 To assign a startup service, under Startup services, select the service from the Available
Services list, and click .
Repeat this step for each service you want to add as a startup service for the package.
6 To add a replication service, do the following:
a Under Replication Services, click .
b In the Enter Input Values dialog box, in the Service field, do one of the following:
Type the service name in the format: folderName:serviceName
Click to navigate to and select the service that you want to use as a
replication service.
c Click OK.
d Repeat these steps for each service you want to add as a replication service.
Tip! If you remove a startup service that invoked a service in another package and the
package was identified as a package dependency, make sure you remove the package
dependency after you remove the startup service.
1 In the Navigation panel, select the package for which you want to remove startup,
shutdown, or replication services.
2 On the File menu, click Open.
3 In the editor, click the package’s Startup/Shutdown/Replication Services tab.
4 Do one or more of the following:
To remove a startup service, under Startup services, select the service you want to
remove from Selected services list, and click .
To remove a shutdown service, under Shutdown services, select the service you
want to remove from the Selected services list, and click .
To remove a replication service, under Replication services, select the replication
service you want to remove and click .
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Basic Concepts
In webMethods Developer, you can manage changes to elements during development by
locking them. This prevents two different users from editing an element at the same time.
You can lock elements such as flow services, Java services, schemas, and specifications.
All elements in Developer’s Navigation panel are read‐only until you lock them. You can
edit an element only if you own the lock on the element. However, you can use and run a
service regardless of its lock status, as long as you have Execute access to the service. For
details, see Chapter 5, “Assigning and Managing Permissions”.
This chapter describes local locking on the Integration Server, which is the default
locking mode of Developer. If you enable Developer’s VCS Integration feature, elements
are locked and unlocked when you check them out of or into your version control system
repository. For more information about implementing and using the VCS Integration
feature, see the webMethods Version Control System Integration Developer’s Guide in the
webMethods_directory\_documentation directory.
What Is a Lock?
A lock on an element prevents another user from editing that element. There are two
types of locks: user locks and system locks. When an element is locked by you, you have a
user lock. The element is read‐only to all other users on the Integration Server. Another
user cannot edit the element until you unlock it.
When an element’s supporting files (node.xml, for example) are marked read‐only on the
Integration Server, the element is system locked. For example, the server administrator has
the ability to mark an element’s supporting files on the server as read‐only, in which case
they are system locked. To edit the element, you must ask the server administrator to
remove the system lock (that is, make the element’s files writable), and then you must
reload the package in which the element resides.
Important! When an Integration Server has the VCS Integration feature enabled,
system locking is effectively disabled for elements that are checked into the version
control system. The VCS Integration feature will override any read/write status
changes applied manually by a server administrator.
Elements are shown in the following ways in Developer:
Locking Elements
Before you edit an element, you must lock it. This ensures that you are the only person
working on a particular element at a time, preventing the loss of changes. Elements can
only be locked by one user at a time. If the element you need is already locked, request
that the current owner of the lock release it. If the element is system locked, request that
the server administrator release it by making the corresponding server files writable.
Locking Elements
Elements are locked by webMethods username (the name you use to log on to the
Integration Server). Because of this, it is important that you use a distinct username to log
on to the server. If you change usernames, you will be unable to edit or unlock items that
you locked using your old username.
When locking elements, keep the following points in mind:
When you create a new element, it is locked automatically for you.
In order to lock an element, you must have Write access rights to it. For details, see
Chapter 5, “Assigning and Managing Permissions”.
When you lock an element, Developer obtains and locks the latest version of the
element that has been saved on the webMethods Integration Server.
Elements generated by a service (including an adapter service) are not locked
automatically.
When you select multiple elements to lock, some elements in the selection may not be
available to lock because they may be system locked, locked by another user,
elements to which you do not have Write access, or elements that cannot directly be
locked. Developer will notify you that these elements cannot be locked and will lock
the rest.
When you lock an adapter notification, Developer also locks its associated
publishable document type. You cannot directly lock the publishable document type
associated with an adapter notification.
When you lock a folder or package, you only lock existing, unlocked elements within
it. Other users can still create new elements in that folder or package.
Note: Users cannot create Java and C/C++ services in a folder or package while
other users own the lock on the folder or package. These types of services require
that all existing Java and C/C++ services in the folder are unlocked and the user
has Write access to all Java and C/C++ services in the folder. For details, see
“Locking Java and C/C++ Services” on page 91.
When you lock a Java or C/C++ service, Developer locks all other Java or C/C++
services within the folder. For details, see “Locking Java and C/C++ Services” on
page 91.
You cannot lock a listener or connection element.
To lock elements
1 In the Navigation panel, select the elements that you want to lock.
2 On the File menu, click Lock for Edit.
If the elements were successfully locked, a green check mark appears next to their
icons in the Navigation panel. If one or more of the elements could not be locked (for
example, if they are system locked, locked by another user, or elements to which you
do not have Write access), Developer displays a dialog box listing them. For
information about troubleshooting lock problems, see “Lock/Unlock Problems” on
page 99.
Tip! You can also lock an element that is open in the editor by right‐clicking the
element’s tab or title bar and then clicking Lock for Edit.
Before you save a Java or C/C++ service, multiple corresponding files must be writable on the
server. A single Java or C/C++ service corresponds to the following files:
.java
.class
.ndf
.frag (may not be present)
Before you save a Java or C/C++ service, all of the preceding files must be writable.
Therefore, make sure that all system locks are removed from those files before saving.
Locking Templates
A template can be used with one or more services on the Integration Server. Currently,
you cannot lock a template as an entity, only the service to which it is attached. Following
are considerations for working with templates in a cooperative development
environment.
To create or edit a template for a service, you must have the service locked.
The template for a service can change without your knowledge. Since a template can be
attached to one or more services, keep in mind that a shared template can change
without your knowledge. For example, if your template is attached to a service that
another user locks and edits, that user can change your template.
Important! Before you system lock an element, always verify that it is not locked by a
user on the Integration Server. If an element becomes system locked while a user is
editing it, the user will not know until he or she tries to save changes to the element. If
this occurs, make the element’s corresponding files writable on the server. After this is
done, the user can save his or her changes to the element.
When viewing an element’s lock status, keep the following points in mind:
If the element has been system locked since you last reloaded the package, Developer
will not show the system lock status in the Locking Status dialog box until you reload
the package.
When another user unlocks an element, you must refresh the Navigation panel to
reflect the updated status. Similarly, when the server administrator removes a system
lock from an element, you must reload the package in which the element resides to
reflect the updated status.
1 In the Navigation panel, select the element for which you want to view the status.
2 On the File menu, click Lock Status. The following dialog box appears if the element is
locked by someone else. A similar dialog appears if the element is system locked or
locked by you.
You can unlock individual elements from this dialog box by pressing the CTRL key as
you click each element and then clicking Unlock. You can unlock all elements by clicking
Unlock All. For more information about unlocking elements, see “Unlocking Elements” on
page 94.
Unlocking Elements
After you edit an element and save changes to the server, you should unlock it to make it
available to other users. There are several ways to unlock elements, depending on
whether you are a member of the Developers ACL or the Administrators ACL. If you are
a developer, you can unlock elements in Developer. If you are an administrator, you can
unlock elements in the Integration Server Administrator as well as in Developer.
1 In the Navigation panel, select the elements that you want to unlock.
Note: Be sure to save changes to the elements before you attempt to unlock them.
2 On the File menu, click Unlock.
3 If the elements you want to unlock contain unsaved changes, Developer alerts you
that the elements cannot be unlocked until you save the changes. Click OK to close the
alert dialog box. Then, save the changes and repeat the unlock action.
4 If one of the elements you selected to unlock is a publishable document type
associated with an adapter notification, and you did not also select the adapter
notification, Developer alerts you that the elements cannot be unlocked. Click OK to
close the alert dialog box. Then, reselect the elements (including the appropriate
adapter notifications) and repeat the unlock action.
The Navigation panel refreshes and the green check mark next to the element disappears.
Tip! You can also unlock elements using the following techniques:
To unlock an element that is open in the editor, right‐click the element’s tab or title
bar and then click Unlock.
To unlock all elements to which you own the lock, use the ToolsMy Locked
Elements command.
1 In the Integration Server Administrator, under Packages, click Management.
2 Click View Locked Elements. The following screen appears, showing all elements that
have user locks and system locks.
3 Click Unlock Elements. The following screen appears.
4 Select the elements that you want to unlock (after informing users if necessary) and
click Unlock Selected Elements.
Developers using webMethods Developer should refresh their Navigation panel to
update their view of the lock status of all elements.
Important! If you receive a “failed to unlock” message, it means that the server files for
a locked element were deleted from the server. Use the Sync to Name Space command
to update the Integration Server Administrator’s view of locked elements.
1 If you do not know the names of the server files that correspond to the element, use
the Lock Status command in Developer. For details, see “Viewing an Element’s
Corresponding Server Files” on page 98.
2 On the server’s file system, remove the read‐only properties from the files that
correspond to the element to make the files writable.
3 Reload the package on the Integration Server that contains the element. The updated
status is reflected in the Integration Server Administrator. Refresh the Navigation
panel in Developer to view the updated status.
Important! If you accidentally applied a system lock to an element that was already
locked by another user, remove the system lock but DO NOT have the user reload the
package in webMethods Developer. (Reloading the package in Developer will
discard their edits.) The user can then save the element without losing the changes he
or she made to it while you had the element system‐locked.
1 In the Navigation panel, select the elements for which you want to view the server file
names.
2 On the File menu, click Lock Status.
The following dialog box shows the server files associated with a flow service named
ApplyCreditMemo. These server files are system locked (that is, they are not writable on
the server).
Note: After a server administrator removes a system lock from an element, you
must reload the package in which the element resides to reflect the unlocked
status.
Important! When an Integration Server has the VCS Integration feature enabled, the
Automatically unlock upon save option must be disabled.
To automatically unlock flow services, IS document types, and specifications after saving
To
1 On the Tools menu, click Options. The Options dialog box appears.
2 Click General.
3 Under Navigation Panel, select the Automatically unlock upon save check box.
4 Click OK.
Troubleshooting
This section addresses common problems that may arise when implementing cooperative
development with webMethods components.
Lock/Unlock Problems
The Lock for Edit and Unlock commands are disabled.
Possible causes are:
The Integration Server to which you are connected may have the
watt.server.ns.lockingMode property configured to “no locking” or “system locking
only.” For details, contact your server administrator.
You have selected multiple elements to lock or unlock and your selection contains of
one or more of the following:
A server
A folder or package and its contents
A package and any other element
An adapter notification record
When I try to lock an element, I get an exception message.
The element may be locked by someone else, system‐locked (marked read‐only on the
server), or you may not have Write access. Refresh the Navigation panel. If a lock is not
shown but you still cannot lock the element, reload the package. In addition, make sure
that you are a member of the ACL assigned for Write access to the element by checking
the element’s Permissions property in the Properties panel.
I can’t unlock a Java or C service.
If there is another Java or C service that is locked by another user or system locked in the
same folder, then you cannot unlock any Java or C services in that folder. This is because
those services share the same .java and .class files on the Integration Server.
I can’t unlock elements since I changed my username.
You can only unlock elements that you have locked with your current username for the
session. If you have changed usernames, log back in to the server with your old username
and then unlock the elements.
If the administrator has deleted your username, contact him or her to unlock the elements
on the server. You can assist the administrator by using the Lock Status command to
identify the names of the system‐locked files on the server that need to be unlocked.
Another user unlocked an element, but it still shows as locked in my Navigation panel.
If it is a Java or C service, reload the package in the Navigation panel. If it is any other
element, use the Refresh command to refresh the Navigation panel.
I receive an “element failed to unlock” message when I try to unlock elements in the Integration
Server Administrator.
This indicates that the server files for the locked element were deleted from the server.
You need to update the Integration Server Administrator’s list of unlocked elements by
clicking Sync to Name Space on the Unlock Selected Elements screen. The Sync to Name
Space command runs automatically when the server is started or restarted.
Save Problems
When I try to save an element that I have locked, I get an exception message.
During the time that you had the lock, the element became system‐locked, its ACL status
changed, or a server administrator removed your lock and another user locked the
element. If the exception message indicates that a file is read‐only, then one or all of the
files that pertain to that element on the server are system‐locked. Contact your
administrator to remove the system lock. After this is done, you can save the element and
your changes will be incorporated.
If the exception message indicates that you cannot perform the action without ACL
privileges, then the ACL assigned to the element has been changed to an ACL in which
you are not an Allowed user. To preserve your changes to the element, contact your
server administrator to:
1 Remove your lock on the element.
2 Lock the element.
3 Edit the ACL assigned for Write access to the element, to give you access.
4 Unlock the element.
You can then save your changes to the element.
Other Problems
I can’t create a new Java or C service.
Another Java or C service is locked in the folder in which you want to create the new
service, or you do not have Write access to all Java or C services in the folder. All of them
must be unlocked or locked by you and you must have Write access to add a new Java or
C service to the same folder. See “Lock/Unlock Problems” on page 99.
I can’t delete a package.
One of the elements in that package is system‐locked (read‐only) or locked by another
user. Contact your administrator or contact the user who has the element locked in the
package.
The webMethods Integration Server went down while I was locking or unlocking an element.
The action may or may not have completed, depending on the exact moment at which the
server ceased action. When the server is back up, restore your session and look at the
current status of the element.
Where is the lock information stored (such as names of elements that are locked, when they were
locked, etc.)?
The information is stored internally in Repository version 4, and in the VCS repository, if
you are using VCS.
Important! It is not recommended that you use Cooperative Development functionality
in an Integration Server cluster. Locking information for elements could be
inadvertently shared with another Integration Server in the cluster. Use a standalone
Integration Server, not a cluster, while developing to eliminate these Cooperative
Development problems.
Basic Concepts
In addition to controlling access to elements on an individual user basis using locking,
you can also control access by groups of users using access control lists (ACLs). Typically
created by a system administrator, ACLs allow you to restrict access on a broader level.
For example, if you have a production package and a development package on the
webMethods Integration Server, you can restrict access to the production package to
users in an Administrators ACL, and restrict access to the development package to users
in a Developers ACL.
Within ACLs, you can also assign different levels of access, depending on the access that
you want different groups of users to have. For example, you may want a “Tester” ACL
to only have Read and Execute access to elements. Or, you may want a “Contractor” ACL
that denies List access to sensitive packages on the webMethods Integration Server, so
that contractors never see them in webMethods Developer.
What Is an ACL?
An ACL controls access to packages, folders, and other elements (such as services, IS
document types, and specifications) at the group level. An ACL identifies groups of users
that are allowed to access an element (Allowed Groups) and/or groups that are not
allowed to access an element (Denied Groups). When identifying Allowed Groups and
Denied Groups, you select from groups that you have defined previously.
There are four different kinds of access: List, Read, Write, and Execute.
List controls whether a user sees the existence of an element and its metadata; that is,
its input and output, settings, and ACL permissions. The element will be displayed
on screens in the Developer and the Integration Server Administrator.
Read controls whether a user can view the source code and metadata of an element.
Write controls whether a user can update an element. This access also controls
whether a user can lock, rename, or delete an element or assign an ACL to it.
Execute controls whether a user can execute a service.
For more details about these types of access, see the webMethods Integration Server
Administrator’s Guide.
The server does not check the ACLs of any of the internally invoked services (those
services invoked by the externally invoked service). However, you can set up the security
settings for a service so that webMethods Integration Server checks the ACL assigned to
the service every time it is invoked, whether directly by a client or by another service. For
details, see “The Permissions Properties” on page 107.
The following diagram illustrates the points at which ACL checking occurs when a client
requests a service.
1
Client Purch:SubmitPO
Purch:SubmitPO
2
INVOKE Purch:LogPO Purch:LogPO
3
INVOKE Purch:CreditAuth Purch:CreditAuth
4
INVOKE Purch:SendPO Purch:SendPO
Stage Description
1 The client (such as another application or a DSP) requests the Purch:SubmitPO
service on the local webMethods Integration Server. webMethods Integration
Server checks the ACL of the Purch:SubmitPO service (the externally invoked
service). The server executes the service only if the client is invoking the service
on the behalf of a user that is a member of an allowed group and is not a
member of a denied group for the ACL assigned to the service.
2 The Purch:SubmitPO service invokes the Purch:LogPO service. Because the
Purch:LogPO service is invoked by the externally invoked service and is located
on the same server as the externally invoked service, webMethods Integration
Server considers the Purch:LogPO service to be internally invoked.
Consequently, the server does not check the ACL of the Purch:LogPO service
before executing it.
3 The Purch:SubmitPO service invokes the Purch:CreditAuth service. Like the
Purch:LogPO service, webMethods Integration Server considers the
Purch:CreditAuth service to be an internally invoked service. Consequently, the
server does not check the ACL of the Purch:CreditAuth service before executing it.
4 The Purch:SubmitPO service invokes the Purch:SendPO service. Like the Purch:LogPO
and Purch:CreditAuth services, webMethods Integration Server considers the
Purch:SendPO service to be an internally invoked service. The server does not
check the ACL of the Purch:SendPO service before executing it.
Note: Any service that the Purch:SubmitPO flow service invokes could also be invoked
directly by the client. For example, if the client directly invokes the Purch:SendPO
service, the server checks the ACL of the Purch:SendPO service. If the client is invoking
the service on the behalf of a user that is a member of an allowed group and not a
member of a denied group, then the server executes the Purch:SendPO service.
1 Make sure that the ACL you want to assign exists on the Integration Server. If not,
create the ACL in the Integration Server Administrator. For details, see the
webMethods Integration Server Administrator’s Guide.
2 In the Navigation panel, click the package or folder to which you want to assign an
ACL.
3 On the File menu, click Open.
4 In the editor, click the title bar of the package or folder to give it the focus.
5 In the Permissions category of the Properties panel, select the ACLs that you want to
assign for each level of access. For details, see “The Permissions Properties” on
page 107.
Important! For List, Read, and Write access, you can only assign ACLs of which you
are a member. If you cannot assign an ACL to an element for List, Read, or Write
access, you probably are not a member of a user group in the Allowed list of that
ACL. To verify, use the ToolsACL Information command. To obtain access to an
ACL, contact your server administrator.
6 Save the element. If an error message appears, check to make sure that you are a
member of each ACL that you assigned to the element.
1 Make sure that the ACL you want to assign exists on the Integration Server. If not,
create the ACL in the Integration Server Administrator. For details, see the
webMethods Integration Server Administrator’s Guide.
2 Open the element to which you want to assign an ACL.
3 In the Permissions category of the Properties panel, select the ACLs that you want to
assign for each level of access. For details, see “The Permissions Properties” on
page 107.
Important! For List, Read, and Write access, you can only assign ACLs of which you
are a member. If you cannot assign an ACL to an element for List, Read, or Write
access, you probably are not a member of a user group in the Allowed list of that
ACL. To verify, use the ToolsACL Information command. To obtain access to an
ACL, contact your server administrator.
4 Save the element. If an error message appears, check to make sure that you are a
member of each ACL that you assigned to the element.
Note: You can view the users and groups that compose the ACLs on the Integration
Server to which you are connected by using the ToolsACL Information command. This
information is read only; to edit ACLs, users, and groups, use the Integration Server
Administrator.
Note: An element can inherit access from all elements except a package.
...denies access to
members of the
Anonymous group...
Field Description
ACLs The ACLs defined on the Integration Server to which you are
connected. These include the default ACLs that were installed with
the server.
User Group Allowed. The user group(s) that have been explicitly allowed to
Association for access the packages, folders, services, or other elements
‘[ACL]’ associated with this ACL.
Denied. The user group(s) that have been explicitly denied access
to the packages, folders, services, or other elements associated
with this ACL.
Resulting Users The names of users that the ACL authorizes, given the current
for ‘[ACL]’ settings in the Allowed and Denied lists. The server builds this list by
looking at the groups to which each user belongs and comparing
that to the groups to which the ACL allows or denies access. For
details on how the server determines access, see the webMethods
Integration Server Administrator’s Guide.
Note: When an Integration Server has the VCS Integration feature enabled, an element
is locked when it is checked out of the version control system. With the appropriate
ACL permissions, you are able to check out (lock) and check in (unlock) elements,
folders and packages.
Troubleshooting
I receive a “Cannot perform operation without Write ACL privileges” message when I try to create an
element.
You are not a member of the ACL assigned to the folder in which you want to save the
element. To verify, check the Permissions category of the Properties panel. If you had
previously been able to save the element, the ACL settings may have changed on the
server since you last saved it. See “Troubleshooting” on page 99 in Chapter 4, “Locking
and Unlocking Elements”.
I receive an “element already exists” message when I try to create an element.
There may be an element with the same name on the Integration Server, but you may not
be able to see it because you do not have List access to it. Try a different element name, or
contact your server administrator.
I can’t assign an ACL to an element.
Make sure that you have locked the element and that you are a member of the List, Read,
or Write ACL that you want to assign. To verify, use the ToolsACL Information command.
I can’t see the source of a flow or Java service. However, I can see the input and output.
You do not have Read access to the service. Contact your server administrator to obtain
access.
I receive an exception when I try to lock an element.
The element may be locked by someone else, system locked (marked read only on the
server), or you may not have Write access. Refresh the Navigation panel. If a lock is not
shown but you still cannot lock the element, reload the package. In addition, make sure
that you are a member of the ACL assigned for Write access to the element. To do so, click
the Permissions category of the Properties panel.
I receive an error when I run a command on the Test menu.
You must have a minimum of Read access to trace or step through a service. If you don’t
have Read access to the service when you are tracing, tracing into, stepping through, or
stepping into a service, you will receive an error message.
If you do have Read access to a service but you do not have Read access to a service it
invokes, Developer “steps over” the invoked service but does not display an error
message.
You must also have Read access to a service to set a breakpoint in the service or send an
XML document to the service.
I receive an exception when I try to go to a referenced service from the pipeline.
You do not have List access to the referenced service. Contact your server administrator.
I receive a “Couldn’t find in Navigation panel” message when I try to find a service in the Navigation
panel. However, I know it is on the Integration Server.
If you do not see the service listed in the Navigation panel, you probably do not have List
access to that service. Contact your server administrator.
I can’t copy and paste a Java service.
Check to make sure that you have Write access to all Java services in the folder into which
you want to paste the service, as well as Write access to the folder itself.
Basic Concepts
To successfully build a flow service, you should understand the following basic concepts
and terms.
INVOKE Purch:GetOrders 1
Any service can be invoked within a flow (including other flow services). For instance, a
flow might invoke a service that you create, any of the built‐in services provided with the
webMethods Integration Server, and/or services from a webMethods add‐on product
such as the webMethods JDBC Adapter.
You create flow services using Developer. They are saved in XML files on webMethods
Integration Server.
Important! Although flow services are written as XML files, they are maintained in a
format that can only be created and understood by Developer. You cannot create or
edit a flow service with a text editor.
Purch:SubmitPO
Purch:SubmitPO
INVOKE Purch:GetOrders
A flow service can contain the following types of flow steps:
Invocation Steps
INVOKE Executes a specified service. For more information about this
step, see “The INVOKE Step” on page 157.
Data-Handling Steps
MAP Performs specified editing operations on the pipeline (such as
mapping variables in the pipeline, adding variables to the
pipeline, and dropping variables from the pipeline). For more
information about this step, see “The MAP Step” on page 183.
Control Steps
BRANCH Executes a specified flow step based on the value of a specified
variable in the pipeline. For more information about this step,
see “The BRANCH Step” on page 160.
LOOP Executes a set of flow steps once for each element in a
specified array. For more information about this step, see “The
LOOP Step” on page 178.
REPEAT Re‐executes a set of flow steps up to a specified number of
times based on the successful or non‐successful completion of
the set. For more information about this step, see “The
REPEAT Step” on page 170.
SEQUENCE Groups a set of flow steps into a series. The SEQUENCE step is
implicit in most flow services (that is, the steps in a flow
service are treated as a series). However, at times it is
necessary to explicitly group a subset of flow steps using
SEQUENCE so that they can be treated as a unit. For more
information about this flow step, see “The SEQUENCE Step”
on page 176.
EXIT Controls the execution of a flow step (for example, abort an
entire flow service from within a series of deeply nested steps,
throw an exception without writing a Java service, or exit a
LOOP or REPEAT without throwing an exception). For more
information about this step, see “The EXIT Step” on page 181.
See Appendix A, “webMethods Flow Steps” for a detailed description of each type of
flow step provided by the webMethods flow language. For information about building
each type of flow step, see Chapter 7, “Inserting Flow Steps”.
The pipeline holds the input and output for a flow service
Services in a flow get Flow Service The Pipeline
their input from and
place their output in input ONum:46-77135
the pipeline.
Name:Kings Sport
INVOKE Purch:LogPO
Phone:201-887-1544
output TNum:128824993554
input Acct:128824993554
Total:5732.78
INVOKE Purch:CreditAuth
Qty:20
output AuthNum:TW99123554
input Date:04/04/99
INVOKE Purch:ConvertDate Item:PK8801-NS
output OrderDate:19990404
input Ship:UPS Ground
Terms:30N
INVOKE Purch:SendPO
Freight:65.00
output Status:Received
When you build a flow service, you use Developer to specify how information in the
pipeline is mapped to and from services in the flow.
Input and output parameters define the fields that the service requires as input and generates as
output
Input Output
Name Data Type Name Data Type
AcctNum String AuthCode String
OrderTotal String
Part of the process of creating a service is declaring its input and output parameters (that
is, explicitly specifying the fields it expects as input and produces as output).
A Process Overview
Building a flow service is a process that involves the following basic stages:
The remaining sections in this chapter and the following chapters provide detailed
information about each stage.
Make sure the folder in which you want to create the service already exists and that you have
Write ACL access to it. If the folder does not already exist, create it using Developer. For
information about creating folders, see “Creating New Elements” on page 41. For
information about ACL permissions, see Chapter 5, “Assigning and Managing
Permissions”.
Once the package and folder are in place, use the FileNew command to start the process
of creating a new service. For details, see “Creating New Elements” on page 41.
Important! The flow steps produced by these options are no different than those
produced by manually inserting INVOKE loadXMLNode and INVOKE queryXMLNode
steps in a flow service. After Developer inserts the set of default steps into your flow
service, you can edit the default steps and insert additional steps just as you would
any ordinary flow service.
INVOKE step
MAP step
BRANCH step
LOOP step
REPEAT step
SEQUENCE step
EXIT step
Note: The purpose of declaring input parameters is to define the inputs that a
calling program or client must provide when it invokes this flow service. You do
not need to declare inputs that are obtained from within the flow itself. For
example, if the input for one service in the flow is derived from the output of
another service in the flow, you do not need to declare that field as an input
parameter.
When possible, use variable names that match the names used by the services in the flow.
Variables with the same name are automatically linked to one another in the pipeline.
(Remember that variable names are case sensitive.) If you use the same variable
names used by flow’s constituent services, you reduce the amount of manual data
mapping that needs to be done. When you specify names that do not match the ones
used by the constituent services, you must use the Pipeline tab to manually link them
to one another. For information about the Pipeline tab, see “What Does the Pipeline
Tab Contain?” on page 186.
Avoid using multiple inputs that have the same name. Although Developer permits you to
declare multiple input parameters with the same name, the fields may not be
processed correctly within the service or by services that invoke this service.
Make sure the variables match the data types of the variables they represent in the flow. For
example, if a service in the flow expects a document list called LineItems, define that
input variable as a document list. Or, if a service expects a Date object called
EmploymentDate, define that input variable as an Object and apply the java.util.Date
object constraint to it. For a complete description of the data types supported by
Developer, see Appendix C, “Supported Data Types”.
Declared input variables appear automatically as inputs in the pipeline. When you select the
first service or MAP step in the flow, the declared inputs appear under Pipeline In.
Important! If you edit a cached service by changing the inputs (not the pipeline), you
must reset the server cache. If you do not reset it, the old cached input parameters will
be used at run time. To reset the service cache from Developer, select the service and
then click the Reset button next to Reset Cache in the Properties panel. To reset the
service cache from Integration Server Administrator, select Service Usage under Server
in the Navigation panel. Select the name of the service and an information screen for
that service appears. Click Reset Server Cache.
Note: If you intend to use this service with a Broker/local trigger or a JMS trigger,
make sure the input signature conforms to the requirements for each of those trigger
types. For more information about creating Broker/local triggers, see the Publish‐
Subscribe Developer’s Guide. For more information about creating JMS triggers, see the
webMethods Integration Server JMS Client Developer’s Guide.
Input/Output tab
For a flow service, the input side describes the initial contents of the pipeline. In other
words, it specifies the variables that this flow service expects to find in the pipeline at run
time. The output side identifies the variables produced by the flow service and returned
to the pipeline.
You can complete the Input/Output tab in the following ways:
Reference a specification. A specification defines a set of service inputs and outputs. You
can use a specification to define input and output parameters for multiple services.
When you assign a specification to a service, you cannot add, delete, or modify the
declared variables using the service’s Input/Output tab.
Reference an IS document type. You can use an IS document type to define the input or
output parameters for a service. When you assign an IS document type to the Input or
Output side of the Input/Output tab, you cannot add, modify, or delete the variables on
that half of the tab.
You insert a reference to an IS document type in one of three ways:
By typing the fully qualified name of the IS document type in the Input or Output
field
By clicking to select an IS document type from a list
By dragging an IS document type on the same server from the Navigation panel
to the box below the Validate input or Validate output check boxes
With the first two methods, the variables within the IS document type become the
input or output signature for the service. You cannot add, modify, or delete the
variables on that half of the tab. With the third method, the IS document type
reference becomes the top‐level document in the signature. You cannot modify or
delete the variables that are contained within the referenced IS document type but
you can add other variables to that half of the tab.
1 Open the service for which you want to declare input and output parameters.
2 In the editor, click the Input/Output tab for that service.
3 If you want to reference a specification, do the following:
4 If you want to reference an IS document type for the input or output parameters of
the service, do the following:
a In the Input or Output field (depending on which half of the specification you want
to assign the IS document type to), type the IS document type name or click to
select it from a list. You can also drag an IS document type from the Navigation
panel to the box below the Validate input or Validate output check boxes.
b If you assigned an IS document type to both the Input and Output sides of the
Input/Output tab, skip the rest of this procedure. Otherwise, continue to the next
step to specify the variables in the other half of the tab.
Important! When an IS document type is assigned to the Input or Output side, you
cannot add, delete, or modify the declared variables on that half of the Input/Output
tab.
5 For each input or output variable that you want to define, do the following:
a Select the half of the Input/Output tab (Input or Output) where you want to define the
variable by clicking anywhere in that half’s large white text box.
b Click on the toolbar and select the type of variable that you want to define.
c Type the name of the variable and press ENTER.
d With the variable selected, set variable properties and apply constraints in the
Properties panel (optional).
e If the variable is a document or a document list, repeat steps b–d to define and set
the properties and constraints for each of its members. Use to indent each
member beneath the document or document list variable.
6 If you want to enter any notes or comments about the input and output parameters,
type your comments on the Comments tab.
Note: Output templates are optional. If a service has an output template assigned to it,
the server automatically applies the template to the results of the service (that is, the
contents of the pipeline) whenever that service is invoked by an HTTP client. If a
service does not have an output template, the server simply returns the results of the
service in the body of an HTML document, formatted as a two‐column table.
When using output templates, keep in mind that:
A service can have at most one output template assigned to it at a time (you can
dynamically change the output template assignment at run time, however).
You can assign the same output template to more than one service.
If you assign an existing output template to a service, the output template must reside
in the IntegrationServer_directory\packages\packageName\templates directory, where
packageName is the package in which the service is located.
You can reference one output template from within another.
You can specify the encoding in which to save the template (for example, SJIS, a type
of Japanese encoding). The Integration Server is optimized for the UTF‐8 encoding.
You should not change this setting unless you are sure that you want to use another
encoding.
1 Open the service to which you want to assign an output template.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Output template category of the Properties panel, do one of the following to
update the Name field:
If you want to assign a new output template to the service, type the name of the
new output template or accept the system default output template name of
FolderName_ServiceName.
If you want to assign an existing output template to the service, type the file name
of the existing output template. You do not need to include the path information
or the file name extension.
Important! Make sure the existing output template resides in the
IntegrationServer_directory\packages\packageName\templates directory, where
packageName is the same package in which the service is located.
4 In the Type list, do one of the following to specify the format for the output template:
To... Select...
Assign an HTML output template to the service html
Assign an XML output template to the service xml
Assign a WML output template to the service wml
Assign an HDML output template to the service hdml
Note: The Type you select determines the extension for the output template file
(*.html, *.xml, *.wml, or *.hdml). In cases where the output is returned to a Web
browser, the Type also determines the value of the HTTP “Content‐Type” header
field (for example, “text/html,” “text/xml,” “text/vnd.wap.wml,” or “text/x‐
hdml“).
5 Do one of the following:
If you assigned a new output template to the service, click New to create the
output template.
If you assigned an existing output template to the service and you want to edit the
template, click Edit.
Select the encoding used to create the template file and click OK. (By default,
Developer uses UTF‐8 to create output template files.)
6 In the template dialog box, create or edit the output template by typing HTML, XML,
WML, or HDML content, and/or by inserting template tags. For more information
about creating an output template, see the Dynamic Server Pages and Output Templates
Developer’s Guide.
7 In the File Encoding list, select the encoding in which you want the template file saved.
The encoding is used by the Integration Server to send the template to the browser
and to interpret data posted in the resulting page in the browser.
The default encoding is Unicode (UTF8). You should not change this setting unless
you are sure that you wish to use another encoding. The Integration Server is
optimized for the UTF‐8 encoding. The encoding you choose also applies to any
localized (translated) versions of the template that you may create, so you should
choose a character encoding that supports all of the languages for which you will
create localized templates. For details, see the Dynamic Server Pages and Output
Templates Developer’s Guide.
If you do change this setting, make sure that your XML or HTML file contains the
proper encoding or META tag for the encoding you use, as this may affect the
browser or parser performance outside the Integration Server.
8 Click Save.
Important! After editing a template in Developer, do not edit it outside of Developer.
This will affect the interpretation of the encoding settings and may result in
characters being lost or misinterpreted.
Important! The Runtime properties on the Properties panel should only be set by
someone who is thoroughly familiar with the structure and operation of the selected
service. Improper use of these options can lead to a service failure at run time and/or
the return of invalid data to the client program.
Important! Do not use the stateless option unless you are certain that the service
operates as an atomic unit of work. If you are unsure, set the Stateless property in the
Runtime category to False.
1 Open the service that you want to configure.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Runtime category of the Properties panel, do one of the following to set the
Stateless property:
If the service is a self‐contained, atomic unit of work and does not need access to
state information, select True. The server will remove the client session
immediately after the service executes, and no session information will be
maintained for the service.
If the service is part of a multi‐service transaction or if you are unsure of its state
requirements, select False. The server will build and maintain a session object for
this service.
Note: Caching is only available for data that can be written to Repository version 4.
Since nodes cannot be written to Repository version 4, they cannot be cached.
a price list for office equipment if the prices in the list vary depending on the client
who initially connects to the data source.
Services that retrieve information from frequently updated sources. If a service retrieves data
from a data source that is updated frequently, the cached results can become
outdated. Do not cache services that retrieve information from sources that are
updated in real time or near real time, such as stock quote systems or transactional
databases.
Services that are invoked with unique inputs. If a service handles a large number of unique
inputs and very few repeated requests, you will gain little by caching its results. You
might even degrade server performance by quickly consuming large amounts of
memory.
Important! If you edit a cached service by changing the inputs (not the pipeline), you
must reset the server cache. If you do not reset it, the old cached input parameters will
be used at run time. To reset the service cache from Developer, select the service and
then click the Reset button next to Reset Cache in the Properties panel. To reset the
service cache from Integration Server Administrator, select Service Usage under Server
in the Navigation panel. Select the name of the service and an information screen for
that service appears. Click Reset Server Cache.
Important! Use Prefetch carefully. Overuse can quickly exhaust the memory available
for cache.
Important! Do not use Prefetch with Java or C/C++ services that invoke access‐controlled
services. Such services will fail during prefetch because the embedded service will be
invoked without the proper access privileges. To avoid this problem, enable Prefetch
on the invoked services rather than on the Java or C/C++ services that call them.
1 Open the service for which you want to configure caching.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Runtime category of the Properties panel, set Cache results to True.
4 In the Cache expire field, type an integer representing the length of time (in minutes)
that you want the results for this service to be available in cache.
5 If you want to use prefetch, do the following:
a Set Prefetch to True.
b In the Prefetch activation property, specify the minimum number of hits needed to
activate the use of prefetch.
1 Open the service that you want to configure.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Runtime category of the Properties panel, do one of the following to specify the
Execution Locale property:
Select... To...
Language Select one of the ISO 639 codes that represent the language. (2‐
or 3‐letter codes)
Extended Language For future release.
Script Optional. Select one of the 4‐letter script codes in the ISO
15924 registry.
Region Optional. Select one of the ISO 3166‐2 country codes.
IANA Variant Optional. Add or remove a variant code registered by the
IANA.
5 Click OK. The Integration Server will execute the service in the specified locale.
Note: If service auditing is also configured for the service, the Integration Server adds
an entry to the audit log for each failed retry attempt. Each of these entries will have a
status of “Retried” and an error message of “Null”. However, if the Integration Server
makes the maximum retry attempts and the service still fails, the final audit log entry
for the service will have a status of “Failed” and will display the actual error message.
Note: The watt.server.invoke.maxRetryPeriod server parameter specifies the
maximum retry period. To change the maximum retry period, change the value of
this parameter.
To catch a transient error and re‐throw it as an ISRuntimeException, the service must
do one of the following:
If the service is a flow service, the service must invoke
pub.flow:throwExceptionForRetry. For more information about the
pub.flow:throwExceptionForRetry, see the webMethods Integration Server Built‐In
Services Reference.
If the service is written in Java, the service can use
com.wm.app.b2b.server.ISRuntimeException ( ). For more information about
constructing ISRuntimeExceptions in Java services, see webMethods Integration
Server Java API Reference for the com.wm.app.b2b.server.ISRuntimeException
class.
The service retry period must be less than the maximum retry period. For more
information, see “About the Maximum Retry Period” on page 136.
1 Open the service for which you want to configure service retry.
2 In the editor, click the service’s title bar to give the service the focus.
3 Under the Retry on ISRuntimeException category of the Properties panel, in the Max
attempts property, specify the number of times the Integration Server should attempt
to re‐execute the service. The default is 0, which indicates that the Integration Server
does not attempt to re‐execute the service.
4 In the Retry interval property, specify the number of milliseconds the Integration Server
should wait between retry attempts. The default is 0 milliseconds, which indicates
that the Integration Server re‐executes the service immediately.
5 On the File menu, click Save.
Tip! You can invoke the pub.flow:getRetryCount service to retrieve the current retry count
and the maximum specified retry attempts. For more information about this service,
see the webMethods Integration Server Built‐In Services Reference. For more information
about building a service that retries, see “Configuring Service Retry” on page 135.
specifying the name of the collection to which it belongs, similar to the way in which
a state or province name serves to distinguish cities with the same name (for example,
Springfield, Illinois, versus Springfield, Ontario).
Like namespaces in XML, the namespace portion of a universal name is expressed as
a URI. This notation assures uniqueness, because URIs are based on globally unique
domain names.
The namespace portion of the universal name can consist of any combination of
characters that form a valid absolute URI (relative URIs are not supported). For
example, the following are all valid namespace names:
http://www.gsx.com
http://www.gsx.com/gl/journals
http://www.ugmed.ch/résumè
For a complete description of what makes up a valid URI, see RFC 2396 Uniform
Resource Identifiers (URI): Generic Syntax at http://www.ietf.org/rfc/rfc2396.txt.
The local name uniquely identifies a service within the collection encompassed by a
particular namespace. Many webMethods users use a service’s unqualified name as
its local name. Under this scheme, a service named gl.journals:closeGL would have a
local name of closeGL.
Local names follow the same construction rules as NCNames in XML. Basically, a
local name can be composed of any combination of letters, digits, or the following
symbols:
. (period)
‐ (dash)
_ (underscore)
Additionally, the local name must begin with a letter or an underscore. The following
are examples of valid local names:
addCustOrder
authorize_Level1
générent
For specific rules relating to NCNames, see “NCName” definition in the Namespaces
in XML specification at http://www.w3.org/TR/1999/REC‐xml‐names‐19990114.
A universal name can be either an explicit or an implicit universal name.
An explicit universal name is a universal name that you assign to a service by specifying
both a namespace name and a local name in the Properties panel.
Note: The server normalizes universal names according to Unicode Normalization
Form C, as recommended by the Character Model, SOAP, and XML standards. This
ensures that names containing non‐ASCII characters (particularly those with
accented or combining characters) are represented in a standard way.
For information about normalization, see http://www.unicode.org/reports/tr15/
(Unicode Standard Annex #15) and http://www.w3.org/TR/charmod/ (Character
Model for the World‐Wide Web).
1 Open the service whose universal name you want to assign, edit, or view.
2 In the editor, click the service’s title bar to give the service the focus.
3 If you want to assign or edit the service’s universal name, specify the following in the
Universal Name category of the Properties panel:
Note: Many webMethods users use the unqualified portion of the
service name as the local name.
4 On the File menu, click Save.
Note: If you move a service, or a folder containing a service, Developer retains the
service’s explicit universal name. If you copy a service, or a folder containing a service,
Developer does not retain the service’s explicit universal name.
1 Open the service whose universal name you want to delete.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Universal Name category of the Properties panel, clear the settings in the
Namespace name and Local name fields.
4 On the File menu, click Save.
Note: When the Integration Server logs an entry for a service, the log entry contains
the identify of the server that executed the service. The server ID in the log entry
always uses the Integration Server primary port, even if a service is executed using
another (non‐primary) Integration Server port.
Each service has a set of auditing properties located in the Audit category on the service’s
Properties panel. These properties determine when a service generates audit data and
what data is stored in the audit log. For each service, you can decide:
Whether the service should generate audit data during execution.
The points during service execution when the service should generate audit data to
be saved in the audit log.
Whether to include a copy of the service input pipeline in the audit log.
Specifies if a service
generates audit
data. Specifies when a
service generates
Specifies when to audit data during
include the pipeline execution.
in the audit log.
Keep in mind that generating audit data can impact performance. The Integration Server
uses the network to send the audit data to the audit log and uses memory to actually save
the data in the audit log. If a large amount of data is saved, performance can be impacted.
When you configure audit data generation for services, you should balance the need for
audit data against the potential performance impact.
The following sections describe the options for generating audit data and the potential
performance impact of each option.
Note: The audit log can be a flat file or a database. If you use a database, the database
must support JDBC. You can use the Integration Server to view the audit log whether
it is a flat file or a database. If the audit log is a database, you can also use the
webMethods Monitor to view audit data and reinvoke the service. Before you
configure service auditing, check with your Integration Server Administrator to learn
what kind of audit log exists. For more information about the audit log, see the
webMethods Logging Guide.
Never The service never generates audit data. Select this option if
you do not want to be able to audit this service.
When top-level service only The service generates audit data only when it is invoked
directly by a client request or by a trigger. The service does
not generate audit data when it is invoked by another
service (that is, when it is a nested service).
Always The service generates audit data every time it is invoked.
Select this option if the service is a critical service that you
want to be able to audit every time it executes.
Tip! When a service generates audit data, it also produces an audit event. If you want
the audit event to cause another action to be performed, such as sending an e‐mail
notification, write an event handler. Then subscribe the event handler to audit events.
For more information about events and event handlers, see Chapter 14, “Subscribing
to Events”.
The following table describes each option in the Log on property. Keep in mind that every
time the service generates audit data, the Integration Server must capture the data and
write it to the audit log. This can degrade performance.
In both situations, if service execution began but did not complete, the
audit log contains an entry for the start of the service, but no entry for
the end of the service.
Performance Impact: Of all the options under Log on, this option
provides the most verbose and expensive type of audit logging. Every
time it executes, the service generates audit data at two points: the
beginning and the end. The Integration Server must write the audit
data to the audit log twice per service execution. This requires
significantly more disk utilization than the Error only and Error and
success options. At most, the Error only and Error and success options
require the Integration Server to write audit data once per service
execution.
Note: The service generates audit data only when it satisfies the selected option under
Enable auditing and the selected option in the Log on property. For example, if When top-
level service only is selected and the service is not the root service in the flow service, it
will not generate audit data.
The audit log will contain the input pipeline for ServiceA only if it is the top‐level service
(invoked directly by a client or a trigger) and the service ends because of failure. If
ServiceA is not the top‐level service or if ServiceA executes successfully, the audit log will
not contain a copy of the input pipeline.
Note: Including the pipeline in the audit log is more beneficial when the audit log is a
database. The Integration Server can save the pipeline to a flat file audit log; however,
you will not be able to use the pipeline data to reinvoke the service or perform failure
analysis.
Never The Integration Server will never save a copy of the service’s input
pipeline to the audit log. Select this option if you are using a flat file
for the audit log or if you do not want to be able to resubmit the
service to the Integration Server.
Performance Impact: This option requires minimal network bandwidth
because the Integration Server needs to send only the audit data
generated by the service to the audit log.
Note: If you want audit events generated by a service to pass a copy of the input
pipeline to any subscribed event handlers, select On errors only or Always.
Error Auditing
In error auditing, you use the audit log to track and reinvoke failed services. To use the
audit log for error auditing, services must generate audit data when errors occur, and the
Integration Server must save a copy of the service’s input pipeline in the audit log.
With webMethods Monitor, you can only reinvoke top‐level services (those services
invoked directly by a client or by a Broker/local trigger). Therefore, if your intent with
error auditing is to reinvoke failed services, the service needs to generate audit data only
when it is the top‐level service and it fails.
To make sure the audit log contains the information needed to perform error auditing,
select the following Audit properties.
To use the audit log for error auditing, use a database as the audit log.
Service Auditing
When you perform service auditing, you use the audit log to track which services execute
successfully and which services fail. You can perform service auditing to analyze the
audit log and determine how often a service executes, how many times it succeeds, and
how many times it fails. To use the audit log for service auditing, services need to
generate audit data after execution ends.
To make sure the audit log contains the information needed to perform service auditing,
select the following Audit properties.
To use the audit log for service auditing, you can use either a flat file or a database as the
audit log.
To use the audit log to audit for recovery, use a database for the audit log.
Note: Typically, you will audit long‐running services in conjunction with error
auditing, service auditing, or auditing for recovery.
Important! Before you select options for generating audit data, check with your
Integration Server Administrator to determine what kind of audit log exists. An audit
log can be a flat file or a database.
1 Open the service for which you want to configure service auditing. To configure
service auditing, you must have write access to the service and own the lock on the
service.
2 In the editor, click the service’s title bar to give the service the focus.
3 In the Audit category of the Properties panel, select an Enable auditing option to indicate
when you want the service to generate audit data.
For more information about the Enable auditing options, see “Enabling Auditing for a
Service” on page 141.
4 For Include pipeline, select an option to indicate when the Integration Server should
include a copy of the input pipeline in the audit log.
Note: If you want audit events generated by this service to pass a copy of the input
pipeline to any subscribed event handlers, select On errors only or Always.
For more information about the Include pipeline options, including information about
the performance impact, see “Including the Pipeline in the Audit Log” on page 143.
5 For Log on, select an option to determine when the service generates audit data.
For more information about the Log on options, including information about the
performance impact, see “Specifying When Audit Data Is Generated” on page 142.
6 On the File menu, click Save.
Important! The options you select in the Audit category of the Properties panel can be
overwritten at run time by the value of the watt.server.auditLog server property.
Audit Level in
Developer 4.x Enable auditing Include pipeline Log on
None Never Never ‐‐
Brief Always Never Error, success, and start
Verbose Always Always Error, success, and start
A flow report lets you view all aspects of the flow service at once
Input/Output
parameters
Details of each
flow step
1 In the editor, select the service that you want to print.
2 From the File menu, click View as HTML.
3 If you want to print the flow, select your browser’s print command.
Note: When you print a flow service as HTML, only the flow steps currently visible in
the editor appear in the resulting HTML page. To fit all of the steps in a flow service
into the editor (and therefore, into a single HTML page), hide the Navigation, Recent
Elements, Properties, and Results panels to maximize the editor.
Note: You might find it helpful to declare the input and output parameters for a flow
service before you insert flow steps. By first declaring the parameters, it is clear what
data the service expects and what variables are available for use in flow steps.
You insert flow steps into a service using the following toolbar buttons at the top of the
editor. (You cannot directly type a flow step into the editor. All editing is performed
through the toolbar).
To insert a/an... Click this button... For more information, see page...
INVOKE step 157
MAP step 183
BRANCH step 160
LOOP step 178
REPEAT step 170
To insert a/an... Click this button... For more information, see page...
SEQUENCE step 176
EXIT step 181
Note: If you select an existing step in the editor before inserting a new one, Developer
inserts the new step below the one that is selected. If you do not have a step selected,
it adds the new step to the end of the flow. You can move a step to a new location
using the arrow buttons on the toolbar. See the following section, “Changing the
Position of a Flow Step”.
Move the flow step up in the list
Move the flow step down in the list
You can also move a flow step by dragging it up or down with your mouse or by using
the Shift commands on the Compose menu.
This step is a
“child” of the LOOP
step.
To promote or demote a flow step within a parent/child hierarchy, select the step in the
editor, and then use one of the following buttons to move it left or right beneath the
current parent step.
Demote a flow step in the hierarchy (that is, make the selected step a
child of the preceding parent step)
This button will only be available if you select a step that can
become a child.
Promote a flow step in the hierarchy (that is, move the step one level
up in the hierarchy)
Use the
Properties
panel to view
and set the
properties of a
flow step.
Although each type of flow step has a set of unique properties, they all have the
following properties:
Property Description
Comments Assigns an optional descriptive comment to the selected flow step.
Label Assigns a name to the selected flow step. When a label is assigned, that
label appears next to the step in the editor. The label allows you to
reference that flow step in other flow steps. In addition, you use the label
to control the behavior of certain flow steps. For example, the BRANCH
step uses the Label property to determine which alternative it is supposed
to execute.
See “The BRANCH Step” on page 160 and “The EXIT Step” on page 181
for additional information about this use of the label property.
For a complete description of the properties associated with each flow step, see
Appendix A, “webMethods Flow Steps”.
Note: If you are using any adapters (for example, the webMethods JDBC Adapter),
you will have additional built‐in services, which are provided by the adapters. See the
documentation provided with those adapters for details.
1 Open the flow service in which you want to invoke another service. In the editor,
select the step immediately above which you want to insert the INVOKE step.
2 Click on the editor toolbar and then select the service you want to invoke. If the
service you want to invoke does not appear in the list, click Browse to navigate to and
select the service.
Tip! You can also add invoke steps by selecting one or more services in the
Navigation panel and dragging them to the desired position within the flow in
the editor. The services must reside on the same server as the flow service.
3 Complete the following fields on the Properties panel:
Service The fully qualified name of the service that will be invoked at run
time. When you insert a service, Developer automatically assigns
the name of that service to the Service property. If you want to
change the service that is invoked, specify the service’s fully
qualified name in the format folderName:serviceName or click
and select a service from the list.
Timeout Optional. Specifies the maximum number of seconds that this
step should run. If this time elapses before the step completes, the
server waits for the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols. For
example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout
blank.
Validate input Whether or not you want the server to validate the input to the
service against the service input signature. Select True to validate
the input. Select False if you do not want to validate the input.
For information about validating input, see “Performing
Input/Output Validation” on page 259.
Validate output Whether or not you want the server to validate the output of the
service against the service output signature. Select True to validate
the output. Select False if you do not want to validate the output.
For information about validating output, see “Performing
Input/Output Validation” on page 259.
Important! You cannot branch on a switch value and an expression for the same
BRANCH step. If you want to branch on the value of a single variable and you know
the possible run‐time values of the switch variable exactly, branch on the switch value.
If you want to branch on the values of more than one variable or on a range of values,
branch on expressions.
1 Create a list of the conditional steps (target steps) and make them children of the
BRANCH step.
2 In the Properties panel for the BRANCH step, specify in the Switch property the name
of the pipeline variable whose value will act as the switch. For more information
about this property, see “Specifying the Switch Variable” on page 161.
3 In the Label property of each target step, specify the value that will cause that step to
execute. For more information about this property, see “Specifying the Label Value”
on page 161.
If PaymentType is
“COD,” execution
will fall through this
BRANCH step.
Keep the following points in mind when assigning labels to the targets of the BRANCH
step:
You must give each target step a label unless you want to match an empty string. For
that case, you leave the Label property blank. For more about matching an empty
string, see “Branching on Null and Empty Values” on page 164.
Each Label value must be unique within the BRANCH step.
When you specify a literal value as the Label of a child step, the value you specify
must match the run‐time value of the switch variable exactly. The Label property is
case sensitive.
You can use a regular expression as the value of Label instead of a literal value.
You can match a null value by using the $null value in the Label property. For more
information about specifying a null value, see “Branching on Null and Empty Values”
on page 164.
You can designate a default step for all unmatched cases by using the $default value in
the Label property. For more information about using the $default setting, “Specifying
a Default Step” on page 165.
Branching on an Expression
When you branch on an expression, you assign an expression to each child of a branch
step. At run time, the BRANCH step evaluates the expressions assigned to the child
steps. It executes the first child step with an expression that evaluates to true.
To branch on an expression
1 Create a list of the conditional steps (target steps) and make them children of the
BRANCH step.
2 In the Properties panel for the BRANCH step, set Evaluate labels to True.
3 In the Label property of each target, specify the expression that, when true, will cause
the target step to execute. The expressions you create can include multiple variables
and can specify a range of values for variables. Use the syntax provided by
webMethods to create the expression. For more information about expression syntax,
see Appendix D, “Conditional Expressions”.
Each
target step
has an
expression
as the
label.
Keep in mind that only one child of a BRANCH step is executed: the first target step
whose label contains an expression that evaluates to true. If none of the expressions
evaluate to true, none of the child steps are invoked, and execution falls through to the
next step in the flow service. You can use the $default value in the Label property to
designate a default step for cases where no expressions evaluate to true. For more
information about using the $default value, see “Specifying a Default Step” on page 165.
Important! The expressions you create for the children of a BRANCH step need to be
mutually exclusive (only one condition should evaluate to true at run time).
A null value Set the Label property to $null. At run time, the BRANCH step
executes the target step with the $null label if the switch variable is
explicitly set to null or does not exist in the pipeline.
You can use $null with any type of switch variable.
An empty Leave the Label property blank (empty). At run time, the BRANCH
string step executes the target step with no label if the switch variable is
present, but contains no characters.
You can use an empty value only when the switch variable is of type
String.
The following example shows a BRANCH step used to authorize a credit card number
based on the buyer’s credit card type (CreditCardType). It contains three target steps. The
first target step handles situations where the value of CreditCardType is null or where
CreditCardType does not exist in the pipeline. The second target step handles cases where
the value of CreditCardType is an empty string. (Note that the first two target steps are
EXIT steps that will return a failure condition when executed.) The third target step has
the $default label, and will process all specified credit card types.
BRANCH that contains target steps to match null values or empty strings
...and the
$default target
step handles the
rest.
Important! You can only have one default target step for a BRANCH step. Developer
always evaluates the default step last. The default step does not need to be the last
child of the BRANCH step.
Create a SEQUENCE
for each multi-step
alternative...
The SEQUENCE step that you use as a target for a BRANCH can contain any valid flow
step, including additional BRANCH steps. For additional information about building a
SEQUENCE, see “The SEQUENCE Step” on page 176.
1 If you are inserting a BRANCH step into an existing flow service, display that service
in the editor and highlight the step immediately above where you want the BRANCH
step inserted.
2 Click on the editor toolbar.
3 Complete the following fields on the Properties panel:
Comments An optional descriptive comment for this step.
Scope The name of a document (IData object) in the pipeline to which
you want to restrict this step. If you want this step to have access
to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run. If
this time elapses before the step completes, the server waits for
the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %expiration%).
If you do not need to specify a time‐out period, leave Timeout
blank.
Label An optional name for this specific step, or a null, unmatched, or
empty string ($null, $default, blank). For more information about
branching on null or empty values, see “Branching on Null and
Empty Values” on page 164.
Note: If you use this step as a target for another BRANCH or an
EXIT step, you must specify a value in the Label property. For
more information about the EXIT step, see “The EXIT Step” on
page 181.
Switch The name of the String or constrained Object variable whose
value will be used to determine which child step to execute at run
time. Do not specify a switch variable if you set the Evaluate labels
property to True.
4 Insert the conditional steps that belong to the BRANCH (that is, its children) using
the following steps:
a Insert a flow step using the buttons on the editor toolbar.
b Indent the flow step using on the editor toolbar to make it a child of the
BRANCH step.
c In the Label property on the Properties panel, specify the switch value that will
cause this step to execute at run time.
To match... Specify...
That exact string A string
The String representation of the object’s value A constrained
object value
Example for Boolean object true
Example for Integer object 123
Any string fitting the criteria specified by the regular A regular
expression expression
Example /^REL/
An empty string A blank field
A null value $null
Any unmatched value (that is, execute the step if the value $default
does not match any other label)
d Set other properties as needed.
Important! If you are branching on expressions, make sure the expressions you assign
to the target steps are mutually exclusive. In addition, do not use null or empty values
as labels when branching on expressions. The BRANCH step ignores target steps
with a $null label or blank label.
FAILURE Re‐executes the set of child steps if any step in the set fails.
SUCCESS Re‐executes the set of child steps if all steps in the set
complete successfully.
0 Does not re‐execute children.
Any value > 0 Re‐executes children up to this number of times.
-1 or blank Re‐executes children as long as the specified Repeat on
condition is true.
Important! Note that children of a REPEAT always execute at least once. The Count
property specifies the maximum number of times the children can be re‐executed. At
the end of an iteration, the server checks to see whether the condition (that is, failure
or success) for repeating is satisfied. If the condition is true and the Count is not met,
the children are executed again. This process continues until the repeat condition is
false or Count is met, whichever occurs first. (In other words, the maximum number of
times that children of a REPEAT will execute when Count is > ‐1, is Count+1.)
SUCCESS A child within the REPEAT block fails.
FAILURE The Count limit is reached before its children execute
successfully.
If the REPEAT step is a child of another flow step, the failure is propagated to its parent.
If you specify multiple children under a REPEAT step, the failure of any one of the
children will cause the entire set of children to be re‐executed.
The REPEAT step immediately exits a set of children at the point of failure (that is, if
the second child in a set of three fails, the third child is not executed).
When Repeat on is set to FAILURE, the failure of a child within a REPEAT step does
not cause the REPEAT step itself to fail unless the Count limit is also reached.
The Timeout property for the REPEAT step specifies the amount of time in which the
entire REPEAT step, including all of its possible iterations, must complete. When you
use REPEAT to retry on failure, you may want to leave the Timeout value at 0 (no limit)
or set it to a very high value. You can also set the property to the value of a pipeline
variable by typing the name of the variable between % symbols.
As a developer, you must be thoroughly familiar with the processes you include
within a REPEAT step. Make certain that the child steps you specify can safely be
repeated in the event that a failure occurs. You don’t want to use REPEAT if there is
the possibility that a single action, such as accepting an order or crediting an account
balance, could be applied twice.
1 If you are inserting a REPEAT step into an existing flow service, display that service
in the editor and highlight the step immediately above where you want the REPEAT
step inserted.
2 Click on the editor toolbar.
3 Complete the following fields on the Properties panel:
Comments An optional descriptive comment for this step.
Scope The name of a document (IData object) in the pipeline to
which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run. If
this time elapses before the step completes, the server waits for
the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %expiration%).
If you do not need to specify a time‐out period, leave Timeout
blank.
Label An optional name for this specific REPEAT step, or a null,
unmatched, or empty string ($null, $default, blank).
Important! If you use this step as a target for a BRANCH or
EXIT step, you must specify a value in the Label property. For
more information about the BRANCH and EXIT steps, see
“The BRANCH Step” on page 160 or “The EXIT Step” on
page 181.
Count The maximum number of times you want the children to be
re‐executed. If you want to use the value of a pipeline variable
for this property, type the variable name between % symbols
(for example, %servicecount%).
If you want the children re‐executed until they are all
successful (that is, no maximum limit), set this value to –1.
Repeat interval The length of time (in seconds) that you want the server to
wait between iterations of the children.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %waittime%).
Repeat on FAILURE
4 Beneath the REPEAT step, use the following steps to insert each step that you want to
repeat:
a Insert a flow step using the buttons on the editor toolbar.
b Indent that flow step using on the editor toolbar. (Make it a child of the
REPEAT step.)
c Set the properties for the child step as needed.
1 If you are inserting a REPEAT step into an existing flow service, display that service
in the editor and highlight the step immediately above where you want the REPEAT
step inserted.
2 Click on the editor toolbar.
3 Complete the following fields on the Properties panel:
Comments An optional descriptive comment for this step.
Scope The name of a document (IData object) in the pipeline to
which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run.If
this time elapses before the step completes, the server waits for
the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %expiration%).
If you do not need to specify a time‐out period, leave Timeout
blank.
Label An optional name for this specific step, or a null, unmatched,
or empty string ($null, $default, blank).
Important! If you use this step as a target for a BRANCH or
EXIT step, you must specify a value in the label property. For
more information about the BRANCH and EXIT steps, see
“The BRANCH Step” on page 160 or “The EXIT Step” on
page 181.
Count The maximum number of times you want the children to be
re‐executed. If you want to use the value of a pipeline variable
for this property, type the variable name between % symbols
(for example, %servicecount%).
If you want the children re‐executed until any one of them
fails (that is, no maximum limit), set this value to –1.
Repeat interval The length of time (in seconds) that you want the server to
wait between iterations of the children.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %waittime%).
Repeat on SUCCESS
4 Beneath the REPEAT step, use the following steps to insert each step that you want
repeat:
a Insert a flow step using the buttons on the editor toolbar.
b Indent that flow step using on the editor toolbar to make it a child of the
REPEAT step.
c Set the properties for the child step as needed.
Exit the sequence when a step in the sequence fails. (Execution FAILURE
continues with the next flow step in the flow service.) This is the
default behavior of a sequence of steps.
This setting is useful if you have a series of steps that build upon
one another. For example, if you have a set of steps that gets an
authorization code and then submits a PO, you will want to skip the
PO submission if the authorization step fails.
When a SEQUENCE exits under this condition, the SEQUENCE
step fails.
Note: When a SEQUENCE step exits on failure, the Integration
Server rolls back the pipeline contents. That is, the Integration
Server returns the pipeline to the state it was in before the
SEQUENCE step executed.
Exit the sequence when any step in the sequence succeeds. SUCCESS
(Execution continues with the next step in the flow service.)
This setting is useful for building a set of alternative steps that are
each attempted at run time. Once one of the members of the set runs
successfully, the remaining steps in the sequence are skipped.
When a SEQUENCE exits under this condition, the server considers
the SEQUENCE step successful, even if all its children fail. If a child
fails under this condition, any changes that it made to the pipeline
are rolled back (undone), and processing continues with the next
child step in the SEQUENCE.
Execute every step in the sequence even if one of the steps in the DONE
sequence fails.
The server considers a SEQUENCE step successful as long as it
executes all of its children within the specified time‐out limit. The
success or failure of a child within the sequence is not taken into
consideration. If a child fails under this condition, any changes that
it made to the pipeline are rolled back (undone), and processing
continues with the next child step in the SEQUENCE.
Note: Rollback operations are performed on the first level of the pipeline only. That is,
first‐level variables are restored to their original values before the step failed, but the
server does not roll back changes to any documents to which the first‐level variables
refer.
Note: A failure in a MAP step (that is, a failure in one of the transformers) will cause
the containing SEQUENCE to exit when you set Exit on to FAILURE. However, a MAP
step that does not fail will not cause the containing SEQUENCE to exit when you set
Exit on to SUCCESS. That is, a MAP can fail but it does not “succeed.”
You may include any valid flow step within the body of a LOOP, including additional
LOOP steps. The following example shows a pair of nested LOOPs. Note how the
indentation of the steps determines the LOOP to which they belong.
LOOP properties
When you design your flow, remember that because the services within the loop operate
against individual elements in the specified input array, they must be designed to take
elements of the array as input, not the entire array.
For example, if your LOOP executes against a document list called LineItems that contains
children called Item, Qty, and UnitPrice, you would specify LineItems as the Input array for
the LOOP step, but services within the loop would take the individual elements of
LineItems (for example, Item, Qty, UnitPrice, and so forth) as input.
transform InventoryStatus to an array variable that contains the output from each iteration
of the loop.
To collect output from each pass of the loop, specify the name of the output variable that
you want the server to collect for each iteration.
1 If you are inserting a LOOP step into an existing flow service, display that service in
the editor and select the step immediately above where you want the LOOP step
inserted.
2 Click on the editor toolbar.
3 Complete the following fields on the Properties panel:
Comments An optional descriptive comment for this step.
Scope The name of a document (IData object) in the pipeline to
which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout The maximum number of seconds that this step should run.If
this time elapses before the step completes, the server waits for
the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this
property, type the variable name between % symbols (for
example, %expiration%).
If you do not need to specify a time‐out period, leave Timeout
blank.
Label An optional name for this specific LOOP step, or a null,
unmatched, or empty string ($null, $default, blank).
Important! If you use this step as a target for a BRANCH or
EXIT step, you must specify a value in the Label property. For
more information about the BRANCH and EXIT steps, see
“The BRANCH Step” on page 160 or “The EXIT Step” on
page 181.
4 Build the body of the loop using the following steps:
a Insert a flow step using the buttons on the editor toolbar.
b Indent the flow step using on the editor toolbar to make it a child of the LOOP
step.
c Set the properties for the child step as needed.
5 Use the Pipeline tab to link the elements of the input array to the input variables
required by each child of the LOOP step. For more information about using the
Pipeline tab, see Chapter 8, “Mapping Data in a Flow Service”.
Important! When you build a LOOP step, make sure that you specify the output array
variable in the LOOP Output array property before creating a link to the output array
variable within a MAP or INVOKE step in the body of the LOOP. If you specify the
output array variable after creating a link to it, the link will fail at run time. You can
test the step in Developer to see if the link succeeds. If the link fails, delete the link to
the output array variable and then recreate it.
Examples of when to use the EXIT step include to:
Exit an entire flow service from within a series of deeply nested steps.
Throw an exception when you exit a flow or a flow step without having to write a
Java service to call Service.throwError( ).
Exit a LOOP or REPEAT flow step without throwing an exception.
The following flow service contains two EXIT steps that, if executed, will exit the nearest
ancestor LOOP step. If the value of CreditCardType is null or an empty string, the
matching EXIT step executes and exits the LOOP over the ʹ/PurchaseOrdersListʹ step.
Use the EXIT step to exit the nearest ancestor LOOP step
This LOOP
exits when....
...CreditCardType
is null...
...or empty.
1 If you are inserting an EXIT step into an existing flow service, display that service in
the editor and select the step immediately above where you want the EXIT step
inserted.
2 Click on the editor toolbar.
3 Complete the following fields on the Properties panel:
Comments An optional descriptive comment for this step.
Label An optional name for this specific step, or a null, unmatched,
or empty string ($null, $default, blank).
Important! If you use this step as a target for a BRANCH step,
you must specify a value in the Label property. For more
information about the BRANCH step, see “The BRANCH
Step” on page 160.
$loop Nearest ancestor LOOP or REPEAT flow step.
$parent Parent flow step, regardless of the type of step.
$flow Entire flow.
Label Nearest ancestor flow step that has a label that
matches this value.
Note: If the label you specify does not match the
label of an ancestor flow step, the flow will exit
with an exception.
Signal Whether the exit is to be considered a success or a failure.
Specify one of the following:
Specify… To…
SUCCES Exit the flow service or flow step with a success
S condition.
FAILURE Exit the flow service or flow step with a failure
condition. An exception is thrown after the exit.
You specify the error message with the Failure
message property.
Failure message The text of the exception message you want to display. If you
want to use the value of a pipeline variable for this property,
type the variable name between % symbols (for example,
%mymessage%).
This property is not used when Signal is set to SUCCESS.
Initialize the input values for a flow service.
Invoke several services (transformers) in a single step.
Map documents form one format to another. For example, you can map a document
in an XML format to an ebXML format or a proprietary format.
Tip! The MAP step is especially useful for hard coding an initial set of input values in
a flow service. To use it in this way, insert the MAP step at the beginning of your flow,
and then use the Set Value modifier to assign values to the appropriate variables in
Pipeline Out.
For more information about the MAP step, see Chapter 8, “Mapping Data in a Flow
Service”.
1 2
2 The expected state of the pipeline just after the service executes.
Service Out depicts the set of variables that the selected service
produces as output (as defined by its output parameters).
Pipeline Out depicts the set of variables that are expected to be in the
pipeline after the service executes. It represents the set of variables
that will be available to the next service in the flow. If the selected
service (INVOKE step) is the last step in the flow service, Pipeline Out
displays the output variables for the flow service (as declared on the
Input/Output tab).
On the Pipeline tab, you can insert “pipeline modifiers” at this stage
to adjust the contents of the pipeline. For example, you can link
variables, assign values to variables, drop variables from the
pipeline, or add variables to the pipeline. Modifications that you
specify during this stage are performed immediately after the
service executes at run time.
Note: Developer displays small symbols next to a variable icon to indicate validation
constraints. Developer uses to indicate an optional variable. Developer uses the ‡
symbol to denote a variable with a content constraint. For information about applying
constraints to variables, see “Applying Constraints to Variables” on page 255.
The Pipeline In column represents input to the MAP step. It contains the names of all of
the variables in the pipeline at this point in the flow.
The Transformers column displays any services inserted in the MAP step to complete
value transformations. For more information about invoking services in a MAP step,
see “Inserting a Transformer into a MAP Step” on page 214.
The Pipeline Out column represents the output of the MAP step. It contains the names
of variables that will be available in the pipeline when the MAP step completes.
When you first insert a MAP step into your flow, Pipeline In and Pipeline Out are identical.
However, if the MAP step is the only step in the flow service or is the last step in the flow
service, Pipeline Out also displays the variables declared as output in the flow service.
On the Pipeline tab, you can insert “pipeline modifiers” to adjust the contents of the
pipeline. For example, you can link variables from Pipeline In to services in Transformers.
You can also use pipeline modifiers to assign values to pipeline variables, drop variables
from the pipeline, or add variables to the pipeline.
Pipeline Modifiers
Pipeline modifiers are special commands that you apply to adjust the pipeline at run
time. They execute immediately before or after the selected service or transformer,
depending on where you add them on the Pipeline tab. Use the following buttons to add
pipeline modifiers to the pipeline:
Note: When you view the Pipeline tab as HTML, the resulting HTML page displays
only the portion of the pipeline that is visible within the tab. Before you select the View
as HTML command, make sure the Pipeline tab displays the part of the pipeline that you
want to view as HTML.
1 Open the flow service for which you want to print the Pipeline tab.
2 In the editor, select the INVOKE or MAP step for which you want to print the Pipeline
tab.
3 Click anywhere on the Pipeline tab.
4 Scroll or resize the Pipeline tab to display the portion of the pipeline you want to view
as HTML.
5 On the File menu, click View as HTML.
Developer creates an HTML page and displays it in your default browser.
6 If you want to print the pipeline, use your browserʹs print command.
Linking Variables
When you want to copy the value of a variable in a service or document format to another
variable, you link the variables. Developer connects service and pipeline variables on the
Pipeline tab with a line called a link. Creating a link between variables copies the value
from one variable to another at run time.
Within a flow, Developer implicitly links variables whose names are the same and whose
data types are compatible. For example, the service in the following flow takes a variable
called AcctNumber. Because a variable by this name already exists in Pipeline In, it is
automatically linked to the AcctNumber variable in Service In. Developer connects
implicitly linked variables with a gray link.
Pipeline variables
are automatically
linked to service
variables of the
same name.
Important! The Pipeline tab does not display implicit links for a MAP step.
In cases where the services in a flow do not use the same names for a piece of
information, use the Pipeline tab to explicitly link the variables to each other. Explicit
linking is how you accomplish name and structure transformations required in a flow.
Developer connects explicitly linked variables with a solid black line.
On the input side of the Pipeline tab, use the Link modifier to link a variable from the
pipeline to the service. In the following example, the service expects a value called
OrderTotal, which is equivalent to the pipeline variable BuyersTotal (that is, they are
simply different names for the same data). To use the value of BuyersTotal as the value for
OrderTotal, you “link” the pipeline variable to the service using the Link modifier.
At run time, the server will copy the value from the source variable (BuyersTotal) to the
target variable (OrderTotal) before executing the service.
When a pipeline
variable name is
different from the one
used by the service,
use the Link modifier
to connect them.
Important! Do not link variables with different Object constraints. If you link variables
with different object constraints and input/output validation is selected, the run‐time
result is undefined.
All the output variables that a service produces are automatically placed in the pipeline.
Just as you can link variables from the Pipeline In stage to a service’s input variables, you
can link the output from a service to a different variable in Pipeline Out.
In the following example, a variable called TransNumber is linked to the field Num in a
document called TransactionRecord. At run time, the server will copy the value of
TransNumber to Num, and both TransNumber and Num will be available to subsequent
services in the flow.
Developer automatically
adds a service’s output
variables to the pipeline and
implicitly links them.
When you link variables in the pipeline, keep the following points in mind:
The variable that you are linking from is the source. For example, when you link a
variable in Pipeline In to one in Service In, the Pipeline In variable is the source. When
you link a variable in Service Out to one in Pipeline Out, the Service Out variable is the
source.
The variable you are linking to is the target. For example, when you link a variable in
Pipeline In to one in Service In, the Service In variable is the target. When you link a
variable in Service Out to one in Pipeline Out, the Pipeline Out variable is the target.
A Service In variable can be the target of more than one Link modifier only if you use
array indexing or if you place conditions on the links to the variable.
By linking variables to each other, you are copying data from the source variable to the
target variable. (Documents, however, are copied by reference. For more information,
see “What Happens When Integration Server Executes a Link Between Variables?” on
page 196.)
Target variables can be connected to only one source variable. After you draw a link
to a target variable, you cannot draw another link to the target variable. (Two
exceptions to this rule involve array variables and conditional links. For more
information about linking array variables, see “Linking to and from Array Variables”
on page 201. For more information about placing conditions on links between
variables, see “Applying Conditions to Links Between Variables” on page 204.
You cannot create a link to a variable if you already used the Set Value modifier to
assign a value to a variable.
After a Link modifier is executed, both the source and target variables exist in the
pipeline. The target variable does not replace the source variable.
1 In the editor, select the INVOKE or MAP step containing the variables you want to
link.
2 Click the Pipeline tab.
3 If you want to create a link between a variable in Pipeline In and one in Service In, do the
following:
a In Pipeline In, click the pipeline variable you want to use as the source variable.
b In Service In, click the input variable you want to use as the target variable.
c Click on the toolbar.
4 If you want to create a link between a variable in Service Out and one in Pipeline Out, do
the following:
a In Service Out, click the output variable you want to use as the source variable.
b In Pipeline Out, click the pipeline variable you want to use as the target variable.
c Click on the toolbar.
Notes:
If the variable types are incompatible and cannot be linked to one another,
Developer displays a message stating that the operation is not allowed.
If you created a link to or from an array variable, you must specify which element
in the array you are linking to or from. For more information about array linking,
see “Linking to and from Array Variables” on page 201.
If you want to place a condition on the execution of the link, see “Applying
Conditions to Links Between Variables” on page 204.
Do not link variables with different Object constraints. If you link variables with
different object constraints and input/output validation is selected, the run‐time
result is undefined.
Tip! You can also use your mouse to link variables to one another. To do this, select the
source variable and drag your mouse to the appropriate target variable.
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
When this flow service executes, it returns the following results.
In Step 3, the value of the String1 in Document1 was set to “modified.” However, the
value of String1 in Document2 changed also. This is because in Step 2 of the flow service,
the value of Document1 was copied to Document2 by reference. Changes to the value of
Document1 in later flow steps also change the value of Document2.
To prevent the value of the target variable from being overwritten by changes to the value
of the source value in subsequent steps in the flow service, you can do one of the
following:
When working with document variables, link each child of the document variable
individually. This method can be time consuming and might significantly increase the
memory and time required to run the service. However, this might be the best
approach if the target document variable needs only a few values from the source
document variable.
After you link the source variable to a target variable, use the Drop modifier to drop
the source variable. Only the target variable will have the reference to the data. This
method ensures that the value of the target variable will not be overwritten in a
subsequent step, but does not increase the memory and time required to execute the
service.
Create a service that performs a copy by value. Insert this service (as an INVOKE step
or as a transformer) and link the variables to the service instead of linking them to
each other. (In the case of document variables, you could create a Java service that
clones the IData object underlying the document.) In situations where you link one
document variable to another, using a “cloning” service would require less time than
linking the contents of a document variable field by field.
If you link from a document variable to another document variable, the structure of
the source document variable overwrites the structure of the target document
variable.
Two String lists can be combined into one document list through data mapping in the
pipeline. For example, if in the above scenario you also had a String list variable named
bList, and documentList had two String children named aString and bString, you could
combine the two String lists by linking aList to aString and bList to bString.
Tip! You can also convert a String list to a document list (IData[ ] object) by invoking
the built‐in service pub.list:stringListToDocumentList. You can insert the service as an
INVOKE step or as a transformer. For more information about transformers, see
“What Are Transformers?” on page 212. For more information about built‐in services,
see the webMethods Integration Server Built‐In Services Reference.
You can specify an index value when linking to or from an array variable
Note: Developer uses blue links on the Pipeline tab to indicate that properties
(conditions or index values for arrays) have been applied to the link between
variables.
To specify the index for the element in the buyerAddress variable to be copied to the
FirstName field, select the link between the variables, click the Indices property’s Edit
button in the Properties panel to specify the index.
If the source or target variable is an array, Developer displays a text box next to the
variable (in this case, buyerAddress). If the source or target variable is not an array,
Developer displays the words “Field not indexable” next to the variable name (in this
case, FirstName). For example, if you want to link the first element of the buyerAddress
variable to the FirstName field in address, type 0 in the field next to buyerAddress. (Index
numbering in arrays begins at 0.)
Link indices
1 Create a link between the variables using the procedure described in “To create a link
between variables” on page 195.
2 Click the link that connects the variables.
3 On the Properties panel, click the Indices property’s Edit button. Developer displays
the Link Indices dialog box.
4 If the source variable is an array variable, under Source, next to the source variable
name, type the index that contains the value you want to link.
5 If the target variable is an array variable, under Destination, next to the destination
variable name, type the index to which you want to link the source value.
6 Click OK.
Note: At run time, the link (copy) fails if the source array index contains a null value or
if you specify an invalid source or target index (such as a letter or non‐numeric
character). The Integration Server generates journal log messages (at debug level 6 or
higher) when links to or from array variables fail.
1 On the Pipeline tab, select the link that you want to delete.
2 On the Edit menu, click Delete.
not null. After you connect the two variables with the Link modifier, you would edit the
properties and add the condition that needs to be true.
A blue link indicates that a condition is applied to the link connecting the variables
Developer uses a blue link on the Pipeline tab to indicate that properties (that is,
conditions or index values for arrays) have been applied to a link between variables.
Note: You cannot add conditions to the links between implicitly linked variables.
Tip! If the conditions for links to the same target variable are not mutually exclusive,
consider using a flow service containing a BRANCH step instead. In BRANCH steps,
child steps are evaluated in a top to bottom sequence. webMethods Integration Server
executes the first child step that evaluates to true and skips the remaining child steps.
For more information about the BRANCH step, see “The BRANCH Step” on
page 160.
1 Create a link between the variables using the procedure described in “To create a link
between variables” on page 195.
2 Click the link (black line) that connects the variables.
3 On the Properties panel, set the Evaluate copy condition property to True.
4 In the Copy condition property text box, type the condition you want to place on the
link.
For information about the syntax used in conditions, see Appendix D, “Conditional
Expressions”.
Important! When drawing more than one link to the same target variable, make sure
that the conditions assigned to each link are mutually exclusive.
Note: You can temporarily disable the condition placed on a link. For more
information, see “Disabling a Condition Placed on a Link Between Variables” on
page 294.
To view (or change) the value that is assigned to the Set Value modifier, double‐click the
icon next to the variable’s name to open the Input For dialog box.
Note: If a variable to which you assigned a default value is implicitly linked to another
variable in the pipeline, Developer displays a gray link on the Pipeline tab connecting
the variables beneath the icon.
Referencing variables
Enclose the variable
name in % symbols...
You can also format String values by specifying one or more pipeline variables in
conjunction with a literal value. For example, if you specified (%areaCode%) %Phone%, the
resulting string would be formatted to include the parentheses and space. If you specified
%firstName% %initial%. %lastName% , the period and spacing would be included in the
value.
1 In the editor, select the INVOKE or MAP step containing the variable you want to
alter.
2 Click the Pipeline tab.
3 Select the variable to which you want to assign a value.
4 Click on the toolbar.
5 In the Input For dialog box, specify the value you want to assign to this variable.
If you want to assign a literal value to the variable, type that value. The value must
be of the same data type as the variable.
If you want to derive the value from a String variable in the pipeline, type the
name of that variable enclosed in % symbols (for example, %Phone%). Then select
the Perform variable substitution check box.
6 If you want the server to use the specified value only if the variable does not contain a
value at run time, clear the Overwrite pipeline value check box. (If you select this check
box, the server will always apply the specified value.)
1 In the editor, select the INVOKE or MAP step containing the variable with the value
you want to copy and paste.
2 Click the Pipeline tab.
3 Select the you want to copy.
4 Right‐click and select Copy.
5 Select the variable or variables to which you want to assign the copied value,
right‐click and select Paste.
Note: You can only paste the set value if the target variable is the same data type as the
source variable and if the target variable has either an identical structure to the source
variable or has no defined structure.
Important! Once you drop a variable from the pipeline, it is no longer available to
subsequent services in the flow. Do not use the Drop modifier unless you are sure the
variable is not used by services invoked after the point where you drop it.
At run time, the server removes a dropped variable from the pipeline just before it
executes the selected service (if you attach the Drop modifier to a variable in Pipeline In) or
immediately after it executes the selected service (if you attach the Drop modifier to a
variable in Pipeline Out).
If you drop a linked variable from Pipeline In, the server executes the Link modifier before it
drops the variable. The server does not link a null value to the destination variable.
1 In the editor, select the INVOKE or MAP step whose pipeline variables you want to
drop.
2 Click the Pipeline tab.
3 Select the variable that you want to drop.
4 Click on the toolbar.
Important! If you create a new variable in a flow, you must immediately do one of the
following:
– Link a variable to it
– Assign a value to it
– Drop it
If you do not take one of these steps, Developer automatically clears it from the
Pipeline tab.
Note: You might want to drop a variable immediately after adding it if a service
produces a variable that is not declared in the service input or output parameters. The
variable will not appear on the Pipeline tab if it is not an input or output parameter. By
adding and then immediately dropping the variable, you can delete the variable if it
does exist in the pipeline.
1 In the editor, select the INVOKE or MAP step that represents the stage of the pipeline
at which you want to add a new variable.
2 Click the Pipeline tab.
3 Select the point where you want to add the new variable.
4 Click and select the type of variable that you want to create.
5 Type the name of the variable and press ENTER.
6 If the variable is a document or a document list, repeat steps 4 and 5 to define its
member variables. Then use to indent each member variable beneath the
document or document list variable.
7 Assign one of the pipeline modifiers to the new variable (Link, Drop, or Set Value). (If
you do not assign a modifier to the variable, Developer considers it extraneous to the
flow and automatically clears the variable when it refreshes the Pipeline tab.)
Note: Services that you insert using the INVOKE step might also perform value
transformations. However, only transformers can accomplish multiple value
transformations in a single flow step.
You can think of transformers as a series of INVOKE steps embedded in a MAP step. And
like INVOKE steps, when you insert a transformer, you need to create links between
pipeline variables and the transformer. You can also set properties for the transformer
and validate the input and/or output of the transformer. Because transformers are
contained within a MAP step, they do not appear as a separate flow step in the editor.
Transformers are well suited for use when mapping data from one document format to
another. When you map data between formats, you usually need to perform several
name, structure, and value transformations. By using transformers, the flow service in
which you map data between formats could potentially consist of a single MAP step in
where transformers and links between variables handle all of the data transformations. In
this way, you could see your entire document‐to‐document mapping in a single view.
Tip! You can create a flow service that uses transformers to convert data between
document formats (such as an IDOC to an XML document or RosettaNet PIP to a
proprietary format). You could then invoke this service in other flow services each
time you need to convert between the specific document formats before you begin
processing data.
Note: In a MAP step, Developer only displays the links between pipeline variables and
transformers. Developer does not display any implicit linking for a MAP step.
pub.date Transform time and date information from one format to another.
pub.document Transform documents to and from document lists and XML values.
pub.list Transform a String list to a document list (IData[ ] object) and
append items to a document list (IData[ ] object) or a String list.
pub.math Perform simple arithmetic calculations (add, subtract, multiply, and
divide) on integers and decimals contained in string variables.
pub.string Transform string values in various ways (for example, pad,
substring, concat, replace through a lookup table).
For more information about built‐in services, see the webMethods Integration Server Built‐
In Services Reference.
To insert a transformer
1 In the editor, select the MAP step in which you want to insert a transformer.
2 Click the Transformers area on the Pipeline tab.
3 Click on the Pipeline tab toolbar and then select the service you want to invoke.
If the service you want to insert does not appear in the list, select Browse to select the
service from the Navigation panel. The transformer appears under Transformers on the
Pipeline tab.
4 Select the transformer and, in the Properties panel, set its properties:
Service The fully qualified name of the service that will be invoked at
run time as a transformer. When you insert a transformer,
Developer automatically assigns the name of that service to
the service property. If you want to change the service that is
invoked by a transformer, specify the service’s fully qualified
name in the folderName:serviceName format or click to select
a service from a list.
Validate input Whether or not you want to validate the input to the
transformer against the signature of the service. Select True to
validate the input of the transformer. Select False if you do not
want to validate the input of the transformer.
For information about validating transformers, see “Validating
Input and Output for Transformers” on page 218.
Validate output Whether or not you want to validate the output of the
transformer against the signature of the service. Select True to
validate the output of the transformer. Select False if you do
not want to validate the output of the transformer.
For information about validating transformers, see “Validating
Input and Output for Transformers” on page 218.
5 Click OK.
For information about debugging transformers, see “Debugging Transformers” on
page 222.
Tip! When you expand a transformer in the Transformers area of the Pipeline tab, you
can see the Service In variables and the Service Out variables and all of the explicit links
between the transformer and the pipeline. You might find it easier to link transformer
variables when you are zoomed in on the transformer.
Output for a transformer is not automatically added to the pipeline. If you want the
output of a transformer to appear in the pipeline, you need to explicitly link the
output variable to a Pipeline Out variable. If you do not link the output variable to a
Pipeline Out variable, the output variable does not appear in the pipeline.
If you do not link any output variables or the transformer does not have any declared
output variables, the transformer service will not run.
The transformers you insert into a single MAP step act on the same set of pipeline
data.
To provide the cleanest and simplest view when working with transformers, the Pipeline
tab only displays one link between the transformer and a Pipeline In variable and one link
between the transformer and a Pipeline Out variable. (The Pipeline tab displays the links
between the transformer and the highest positioned Pipeline In variable and Pipeline Out
variable to which the transformer is linked.)
1 To create a link between a Pipeline In variable and a transformer variable, do the
following:
a In Pipeline In, select the variable you want to use as input to the transformer and
drag your mouse to the transformer.
b In the Link To list, select the transformer variable to which you want to link the
Pipeline In variable.
Once you link a transformer input variable to a Pipeline In variable, Developer
displays the phrase “has already been chosen” next to the transformer variable in
the Link To list.
c Repeat steps a and b for each transformer input variable you want to link to a
pipeline variable.
2 To create a link between a transformer output variable and a Pipeline Out variable, do
the following:
a Select the transformer and drag your mouse to the variable in Pipeline Out to which
you want to link the transformer variable.
b In the Link From list, select the transformer variable that you want to link to the
selected Pipeline Out variable.
c Repeat steps a and b for each output variable produced by the transformer.
You can link a transformer output variable to more than one Pipeline Out variable.
Important! Developer does not automatically add the output of a transformer to the
pipeline. If you want the output of a transformer to appear in the pipeline after the
transformer executes, you need to explicitly link the output variable to a variable in
Pipeline Out.
Important! If you do not link any output variables or the transformer does not have any
output variables, the transformer will not execute.
Transformer Movement
When you link to and from a selected transformer, it moves up and down in the
Transformers column. This movement or “jumping” is by design to help minimize the
distance between the transformer and the variable you are linking it to.
Transformers exhibit the following behavior or movement:
When a transformer is selected and you select a variable in Pipeline In or Pipeline Out,
the transformer “jumps” or moves up or down in the Transformers column so that it is
directly across from the selected pipeline variable.
When you finish linking a transformer and it is no longer selected, Developer
“anchors” or aligns the transformer next to the highest Pipeline Out variable it is linked
to.
To stop the transformer from jumping, click the transformer again or click in the empty
areas of the Pipeline tab.
Note: To expand your view of the Pipeline tab, drag the movable border above the tab.
The Pipeline tab expands to fit in the Developer window.
What Is Dimensionality?
Dimensionality refers to the number of arrays to which a variable belongs. For example,
the dimensionality of a single String is 0, that of a single String list or document list is 1,
and that of a single String table is 2. A String that is a child of a document list has a
dimensionality of 1. A String list that is a child of a document list has a dimensionality
of 2.
Example
In the following example, the unitPrice variable cannot be linked to num1 because the
unitPrice variable has a dimensionality of 1 ( string (0) + document list (1) = 1) and num1
has a dimension of 0.
Solution
To solve this, you can either:
Change the service invoked by the transformer to accept arrays as data, or
Create a flow service in which a LOOP step loops over the array variable. Then, (in
the same flow service) invoke the service you originally wanted to use as a
transformer, and make that INVOKE step a child of the LOOP. Finally, insert the
resulting flow service as a transformer in the MAP.
Of the two options, changing the service to accept arrays as data results in faster
execution of flow services.
1 In the editor, select the MAP step containing the transformer you want to validate.
2 Click the Pipeline tab.
3 Under Transformers, select the transformer for which you want to validate input or
output.
4 On the Properties panel, for the Validate input property, select True if you want to
validate the input to the transformer against the input parameters of the invoked
service.
5 For the Validate output property, select True if you want to validate the output of the
transformer against the output parameters of the invoked service.
6 Click OK.
Copying Transformers
You may want to use the same transformer more than once in a MAP step. For example,
you might want to convert all the dates in a purchase order to the same format. Instead of
using the button to locate and select the service, you can copy and paste the
transformer service.
You can also copy transformers between MAP steps in the same flow or MAP steps in
different flow services.
Important! Copying a transformer does not copy the links between transformer
variables and pipeline variables or any values you might have assigned to
transformer variables using the Set Value modifier.
To copy a transformer
1 In the editor, select the MAP step containing the transformer service you want to
copy.
2 Click the Pipeline tab.
3 Under Transformers, select the transformer service you want to copy. Right‐click the
transformer and then select Copy.
4 To paste the transformer, click anywhere under Transformers. Right‐click and select
Paste.
5 Link the input and output variables of the transformer using the procedures
described in “Linking Variables to a Transformer” on page 215.
Expanding Transformers
You might find it easier to create links to transformers when you expand the transformer.
When you expand a transformer, you can see the Service In and the Service Out variables
for the transformer and all of the links between the pipeline and the transformer
variables.
When you expand a transformer, you can only perform actions for that transformer, for
example, you can only link variables or set properties for the expanded transformer.
Other transformers and links to other transformers remain hidden until you collapse the
transformer.
To expand the contents of a transformer, click ComposeExpand.
To collapse the contents of a transformer, click ComposeCollapse.
Tip! You can also expand/collapse a transformer by double‐clicking it.
Note: If Integration Server displays a message stating that the transformer cannot
be found, then the service invoked by the transformer has been renamed, moved,
or deleted. You must use the transformer properties to rename the transformer.
See the following section for more information.
Renaming Transformers
If Integration Server displays the message “Transformer not found” when you try to
expand a transformer or when you point the mouse to the transformer, then the service
referenced by the transformer has been renamed, moved, or deleted. You need to change
the Service property of the transformer so that the transformer points to the moved, or
renamed service.
If the service referenced by the transformer has been deleted, you may want to delete the
transformer.
Tip! You can enable safeguards so that you do not inadvertently affect or break other
services when you move, rename, or delete a service. For more information, see
“Specifying Dependency Checking Safeguards” on page 43.
To rename a transformer
1 Use the Navigation panel to determine the new name or location of the service called
by the transformer.
2 Open the flow service containing the transformer you want to rename.
3 In the editor, select the MAP step containing the transformer. Then, on the Pipeline tab,
select the transformer you want to rename.
4 In the Service property on the Properties panel, delete the old name and type in the
service’s new fully qualified name in the folderName:serviceName format, or click to
select a service from a list.
Debugging Transformers
When you test and debug a flow service, you can use the following testing and
debugging techniques with transformers:
Step into a MAP step and step through the execution of each transformer. For more
information about stepping into and out of a MAP step, see “Using the Step Tools
with a MAP Step” on page 288.
Set a breakpoint on a transformer so that service execution stops when the
transformer is encountered. For more information about setting breakpoints, see
“Setting Breakpoints” on page 288.
Disable a transformer so that it does not execute at run time. For more information
about disabling transformers, see “Disabling Transformers” on page 293.
Creating an IS Schema
An IS schema is a “free‐standing” element in the Navigation panel that acts as the
blueprint or model against which you validate an XML document. The IS schema
provides a formal description of the structure and content for a valid instance document
(the XML document). The formal description is created through the specification of
constraints. An IS schema can contain the following types of constraints:
Structural constraints in an IS schema describe the elements, attributes, and types that
appear in a valid instance document. For example, an IS schema for a purchase order
might specify that a valid <lineItem> element must consist of the <itemNumber>,
<size>, <color>, <quantity>, and <unitPrice> elements in that order.
Schema editor
Select a component
in the schema
browser...
Schema Browser
The schema browser displays the components of an IS schema in a format that mirrors
the structure and content of the source file. The schema browser groups the global
element declarations, attribute declarations, simple type definitions, and complex type
definitions from the source file under the top‐level headings ELEMENTS, ATTRIBUTES,
SIMPLE TYPES, and COMPLEX TYPES. For example, the ELEMENTS heading contains
all of the global element declarations from the XML Schema or the DTD.
If the source file does not contain one of these global components, the corresponding
heading is absent. For example, if you create an IS schema from an XML Schema that
does not contain any global attribute declarations, the schema browser does not display
the ATTRIBUTES heading. An IS schema created from a DTD never displays the SIMPLE
TYPES or COMPLEX TYPES headings because DTDs do not contain type definitions.
Note: A DTD does contain attribute declarations. However, the schema browser does
not display the ATTRIBUTES heading for IS schemas generated from DTDs. This is
because an attribute declaration in a DTD associates the attribute with an element
type. Accordingly, the schema browser displays attributes as children of the element
type declaration to which they are assigned. For more information, see the
webMethods Integration Server Schema Reference.
The schema browser uses unique symbols to represent the components of the IS schema.
Each of these symbols relates to a component of an XML Schema or a DTD. The following
table identifies the symbol for each component that can appear in an IS schema.
Note: In the following table, global refers to elements, attributes, and types declared or
defined as immediate children of the <schema> element in an XML Schema. All
element type declarations in a DTD are considered global declarations.
Symbol Description
Element declaration. An element declaration associates an element name with
a type definition. This symbol corresponds to the <element> declaration in
an XML Schema and the ELEMENT declaration in a DTD.
Element reference. An element reference is a reference from an element
declaration in a content specification to a globally declared element.
In an IS schema generated from an XML Schema, this symbol corresponds
to the ref="globalElementName" attribute in an <element> declaration.
In an IS schema generated from DTD, this symbol appears next to an
element that is a child of another element. The parent element has only
element content.
Any element declaration. In XML Schema, an <any> element declaration is a
wildcard declaration used as a placeholder for one or more undeclared
elements in an instance document.
In a DTD, an element declared to be of type ANY can contain any
well‐formed XML. This symbol corresponds to an element declared to be of
type ANY.
Because an <any> element declaration does not have a name, the schema
browser uses ʹAnyʹ as the name of the element.
Attribute declaration. An attribute declaration associates an attribute name
with a simple type definition. This symbol corresponds to the XML Schema
<attribute> declaration or the attribute in a DTD ATTLIST declaration.
Attribute reference. An attribute reference is a reference from a complex type
definition to a globally declared attribute. This symbol corresponds to the
ref="globalAttributeName" attribute in an attribute declaration.
DTDs do not have attribute references. Consequently, attribute references
do not appear in IS schemas generated from DTDs.
Any attribute declaration. An any attribute declaration is a wildcard
declaration used as a placeholder for undeclared attributes in an instance
document. This symbol corresponds to the <anyAttribute> declaration in
an XML Schema.
Because an <anyAttribute> declaration does not specify an attribute name,
the schema browser uses ʹAnyʹ as the name of the attribute.
Symbol Description
Simple type definition. A simple type definition specifies the data type for a
text‐only element or an attribute. Unlike complex type definitions, simple
type definitions cannot carry attributes. This symbol corresponds to the
<simpleType> element in an XML Schema.
If the simple type definition is unnamed (an anonymous type), the schema
browser displays ʹAnonymousʹ as the name of the simple type definition.
Complex type definition. A complex type definition defines the structure and
content for elements of complex type. (Elements of complex type can
contain child elements and carry attributes.) This symbol corresponds to
the <complexType> element in an XML Schema.
If the complex type definition is unnamed (an anonymous type), the
schema browser displays ʹAnonymousʹ as the name of the complex type
definition.
Sequence content model. A sequence content model specifies that the child
elements in the instance document must appear in the same order in which
they are declared in the content model. This symbol corresponds to the
<sequence> compositor in an XML Schema or a sequence list in an element
type declaration in a DTD.
Choice content model. A choice content model specifies that only one of the
child elements in the content model can appear in the instance document.
This symbol corresponds to the <choice> compositor in an XML Schema or
a choice list in a DTD element type declaration.
All content model. An all content model specifies that child elements can
appear once, or not at all, and in any order in the instance document. This
symbol corresponds to the <all> compositor in an XML Schema.
Mixed content. Elements that contain mixed content allow character data to
be interspersed with child elements. This symbol corresponds to the
mixed="true" attribute in an XML Schema complex type definition or a
DTD element list in which the first item is #PCDATA.
Empty content. In an XML Schema, an element has empty content when its
associated complex type definition does not contain any element
declarations. An element with empty content may still carry attributes.
In a DTD, an element has empty content when it is declared to be of type
EMPTY.
If you select an
element
declaration...
When you select a simple type definition, the schema details area looks like the following:
Creating an IS Schema
In Developer, you can create IS schemas from XML Schema definitions, DTDs, and XML
documents that reference an existing DTD. The resulting IS schema contains all of the
defined types, declared elements, and declared attributes from the source file.
Note: The actual work of creating an IS schema is performed by the schema processor.
The schema processor is the subsystem of the webMethods Integration Server that
compiles an IS schema from a source file.
Note: You can find sample XML Schema definitions in the following directory:
Developer_directory\samples\xml\xsd. You can also find XML Schema definitions
and DTDs on the Web sites for these groups: (www.w3c.org and
www.openapplications.org).
To create an IS schema
1 On the File menu, click New.
2 In the New dialog box, select Schema, and then click Next.
3 In the New Schema dialog box, next to Folder, select the folder where you want to save
the IS schema.
4 In the Name field, type a name for the IS schema using any combination of letters,
numbers, and the underscore character. Click Next.
Important! If you specify a name that uses a reserved word or character,
webMethods Integration Server displays an error message. When this happens,
use a different name or try adding a letter or number to the name to make it valid.
For more information about restricted characters for packages, folders, and
elements, see “About Element Names” on page 41.
5 In the New Schema dialog box, select one of the following to specify the source for the
IS schema.
Specify... To...
XML Create an IS schema based on an existing DTD referenced by an XML
document.
DTD Create an IS schema based on a DTD.
XML Create an IS schema based on an XML Schema definition.
Schema
Important! You can create an IS schema from an XML document only if the XML
document references an existing DTD.
6 Click Next.
7 In the Enter the URL or select a local file box, do one of the following:
If you want to base the IS schema on an XML document, DTD, or XML Schema
definition that resides on the Internet, type the URL of the resource. (The URL you
specify must begin with http: or https:.)
If you want to base the IS schema on an XML document, DTD, or XML Schema
definition that resides on your local file system, type the path and file name, or
click to navigate to and select the file.
8 Click Finish. Developer generates the IS schema using the document you specified and
displays it in the editor.
Note: You might receive errors or warnings when creating an IS schema from an XML
Schema definition or DTD. For more information about these errors and warnings,
see Appendix G, “Validation Errors and Exceptions”.
Note: When creating an IS schema from an XML Schema definition, Developer
validates the schema and does not create the IS schema if the XML Schema definition
is not valid. For more information, see “IS Schema Generation Errors and Warnings”
on page 470.
schema named “mySchema” from mySchema.xsd, the schema processor generates an
IS schema named “mySchema_2” for the imported XML Schema.
Redefine. Schema authors can also use <redefine> to include and then redefine type
definitions, model groups, and attribute groups from an external XML Schema in the
same namespace.
This anonymous
simple type can be
edited.
When modifying a simple type definition, keep the following points in mind:
Changes to a simple type definition affect the elements and attributes for which the
simple type is the defined type. For example, if the attribute partNum is defined to be
of type SKU, changes to the SKU simple type definition affect the partNum attribute.
Changes to a global simple type definition in an IS schema do not affect simple types
derived from the global simple type; that is, the changes are not propagated to the
derived types in the IS schema.
Simple types in an IS schema can be used as content constraints for fields in pipeline
validation. Consequently, changes to a simple type also affect every field to which the
simple type is applied as a content constraint.
Tip! You can create a custom simple type to apply to a field as a content type
constraint. For more information about creating a custom simple type and
applying constraints to fields, see “Setting Constraining Facet Values” on
page 233.
Changes to a simple type definition are saved in the IS schema. If you regenerate the
IS schema from the XML Schema definition, your changes will be overwritten.
When you edit the constraining facets applied to a simple type definition, you can
only make the constraining facet values more restrictive. The constraining facets
cannot become less restrictive. For more information about setting values for
constraining facets, see “Setting Constraining Facet Values” on page 233.
Tip! If you want to edit complex type definitions, attribute declarations, element
declarations, or the structure of the schema, you need to edit the XML Schema and
then regenerate the IS schema.
1 Open the IS schema that contains the simple type you want to edit.
2 In the schema browser area of the editor, select the simple type that you want to edit.
The symbol appears next to simple types.
3 In the schema details area, specify the constraining facets that you want to apply to
the simple type. For more information about constraining facets, see “Constraining
Facets” on page 448.
4 On the File menu, click Save.
You can create an IS document type in the following ways:
Create an empty IS document type and define the structure of the document type
yourself by inserting fields.
Create an IS document type from a source file, such as an XML Schema, DTD, or XML
document. The structure and content of the IS document type will match that of the
source file.
Create an IS document type from a Broker document type.
Note: If you intend to make the IS document type publishable, keep in mind that the
Broker has restrictions for field names. If you create a trigger that subscribes to the
publishable document type, any filters that include field names containing restricted
characters will be saved on the Integration Server only. The filters will not be saved on
the Broker, possibly affecting Integration Server performance. For more information,
see the Publish‐Subscribe Developer’s Guide.
1 On the File menu, click New.
2 In the New dialog box, select Document Type and click Next.
3 In the New Document Type dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the IS
document type.
b In the Name field, type a name for the IS document type using any combination of
letters, numbers, and/or the underscore character. For information about
restricted characters, see “About Element Names” on page 41.
c Click Next.
4 Under Select a source, select None to indicate that you want to create an empty IS
document type in which you define the structure and fields.
5 Click Finish.
6 To add fields in the IS document type, do the following:
a Click on the toolbar and select the type of field that you want to define.
b Type the name of the field and then press ENTER.
Note: Developer prevents the insertion of fields named _env in an IS document
type. For details about the _env field, see “The Envelope Field” on page 243.
c With the field selected, set field properties and apply constraints in the Properties
panel (optional).
For more information about setting field properties, see “Specifying Field
Properties” on page 247. For information about applying constraints, see
“Applying Constraints to Variables” on page 255.
d If the field is a document or a document list, repeat steps a–c to define and set the
properties and constraints for each of its members. Use to indent each member
field beneath the document or document list field.
7 On the File menu, click Save.
Note: Developer displays small symbols next to a field icon to indicate validation
constraints. Developer uses to indicate an optional field. Developer uses the ‡
symbol to denote a field with a content constraint. For information about applying
constraints to fields, see “Applying Constraints to Variables” on page 255.
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://usecases/xsd2doc/01"
xmlns:uc="http://usecases/xsd2doc/01" >
<xsd:element name="eltA" type="uc:documentX" />
<xsd:complexType name="documentX">
<xsd:sequence>
<xsd:element name="eltX_E" type="xsd:string" />
<xsd:element name="eltX_F" type="uc:documentY" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="documentY">
<xsd:sequence>
<xsd:element name="eltY_G" type="xsd:string" />
<xsd:element name="eltY_H" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
If you select the option to expand complex types inline, the schema processor generates
the document type as follows. In this example, the schema processor expanded the
complex types named documentX and documentY inline within the new IS document type:
If you select the option to generate complex types as separate document types, the
schema processor generates the document types as follows. In this example, the schema
processor generated three IS document types—one for the complex type named
documentY, one for the complex type named documentX (with a reference to documentY),
and one for the root element eltA (with references to documentX and documentY):
The schema processor generates all three document types in the same folder.
Note: If the complex type is anonymous, the schema processor expands it inline rather
than generate a separate document type.
If the XML Schema you are using to generate an IS document type contains recursive
complex types (that is, element declarations that refer to their parent complex types
directly or indirectly), you can avoid errors in the document type generation process by
selecting the option to generate complex types as separate document types. (Selecting the
option to expand complex types inline will result in infinitely expanding nested
documents.)
1 On the File menu, click New.
2 In the New dialog box, select Document Type and click Next.
3 In the New Document Type dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the IS
document type.
b In the Name field, type a name for the IS document type using any combination of
letters, numbers, and/or the underscore character. For information about reserved
words or characters, see “About Element Names” on page 41.
c Click Next.
4 Under Select a source, select one of the following:
Select... To...
XML Create an IS document type that matches the structure and fields in
an XML document.
DTD Create an IS document type that matches the structure and fields in
a DTD.
XML Schema Create an IS document type that matches the structure and fields in
an XML Schema definition.
5 Click Next.
Note: You might receive errors or warnings when creating an IS document type
from a DTD or XML Schema definition. For more information about these errors
and warnings, see “Validation Errors” on page 452.
An instance of a publishable document type can be published to a Broker or locally
within an Integration Server.
A publishable document type can be used anywhere an IS document type can be used.
For example, you can use a publishable document type to define the input or output
parameters of a service. A document reference field can reference an IS document type or
a publishable document type. You can use a publishable document type as the blueprint
for performing document or pipeline validation.
Tip! Any IS document type can be made into a publishable document type. For
information about making a document type publishable or setting publication
properties, see the Publish‐Subscribe Developer’s Guide.
When you create an IS document type from a Broker document type that references other
elements, Developer will also create an element for each referenced element. The
Integration Server will contain a document type that corresponds to the Broker document
type and one new element for each element the Broker document type references.
Developer also creates the folder in which the referenced element was located. Developer
saves the new elements in the package you selected for storing the new publishable
document type.
For example, suppose that the Broker document type references a document type named
address in the customerInfo folder. Developer would create an IS document type named
address and save it in the customerInfo folder. If a field in the Broker document type was
constrained by a simple type definition declared in the IS schema purchaseOrder, Developer
would create the referenced IS schema purchaseOrder.
An element referenced by a Broker document type might have the same name as an
existing element on your Integration Server. However, element names must be unique on
the Integration Server. Developer gives you the option of overwriting the existing
elements with the referenced elements.
Important! If you choose to overwrite existing elements with new elements, keep in
mind that dependents of the overwritten elements will be affected. For example,
suppose the address document type defined the input signature of a flow service
deliverOrder. Overwriting the address document type might break the deliverOrder flow
service and any other services that invoked deliverOrder.
1 On the File menu, click New.
2 In the New dialog box, select Document Type and click Next.
3 In the New Document Type dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the IS
document type.
b In the Name field, type a name for the IS document type using any combination of
letters, numbers, and/or the underscore character.
c Click Next.
4 Under Select a source, select Broker Document Type, and click Next.
5 In the New Document Type dialog box, do the following:
a In the Broker Namespace field, select the Broker document type from which you
want to create an IS document type. The Broker Namespace field lists all of the
Broker document types on the Broker territory to which the Integration Server is
connected.
b If you want to replace existing elements in the Navigation panel with identically
named elements referenced by the Broker document type, select the Overwrite
existing elements when importing referenced elements check box.
Important! Overwriting the existing elements completely replaces the existing
element with the content of the referenced element. Any elements on the
Integration Server that depend on the replaced element, such as flow services,
IS document types, and specifications, might be affected.
6 Click Finish. Developer automatically refreshes the Navigation panel and displays
beside the document type name to indicate it is a publishable document type.
Notes:
You can associate only one IS document type with a given Broker document type.
If you try to create a publishable document type from a Broker document type
that is already associated with a publishable document type on your Integration
Server, Developer displays an error message.
In the Publication category of the Properties panel, the Broker doc type property
displays the name of the Broker document type used to create the publishable
document type. Or, if you are not connected to a Broker, this field displays Not
Publishable. You cannot edit the contents of this field. For more information about
the contents of this field, see the Publish‐Subscribe Developer’s Guide.
Once a publishable document type has an associated Broker document type, you
need to make sure that the document types remain in sync. That is, changes in one
document type must be made to the associated document type. You can update
one document type with changes in the other by synchronizing them. For
information about synchronizing document types, see the Publish‐Subscribe
Developer’s Guide.
Note: If an IS document type contains a field named _env, you need to delete that field
before you can make the IS document type publishable.
An adapter notification can have an associated publishable document type . When
you create a polling or asynchronous listener adapter notification in Developer, the
Integration Server automatically generates a corresponding publishable document type.
Developer assigns the publishable document type the same name as the adapter
notification, but appends PublishDocument to the name. That is, Developer assigns the
publishable document type the name: NotificationNamePublishDocument. You can use
this publishable document type with triggers and flow services just as you would any
other publishable document type.
In a publishable document type associated with an adapter notification, you can edit only
the Storage type and Time to live publication properties. To make any other modifications to
the publishable document type, you must modify the adapter notification type.
Integration Server automatically applies the changes to the publishable document type.
For information about publication properties, see the Publish‐Subscribe Developer’s Guide.
For more information about creating and using adapter notifications, see the appropriate
adapter user guide. For more information about performing actions on adapter
notifications and their associated publishable document types, see Chapter 2, “Managing
Elements in the Navigation Panel”.
Important! If you use an IS document type as the blueprint for pipeline or document
validation, any changes you make to the IS document type can affect whether the
object being validated (pipeline or document) is considered valid. For more
information about validation, see Chapter 10, “Performing Data Validation”.
Developer displays this message only if a Broker is configured for the Integration Server.
To update the associated Broker document type with the changes, synchronize the
publishable document type with the Broker document type. For more information about
synchronizing document types, see the Publish‐Subscribe Developer’s Guide.
1 Open the IS document type you want to print and click its title bar in the editor to
give it the focus.
2 From the File menu, select View as HTML.
Developer expands any document and document list fields in the IS document type,
creates an HTML page containing the IS document type, and displays the HTML
page in your default browser.
3 If you want to print the IS document type, select your browser’s print command.
1 Open the service to which you want to assign the IS document type.
2 Click the Input/Output tab.
3 In the Input or Output box (depending on which half of the Input/Output tab you want to
apply the IS document type to), type the fully qualified name of the IS document type
or click to select it from a list. You can also drag an IS document type from the
Navigation panel to the box below the Validate input or Validate output check boxes on
the Input/Output tab.
4 On the File menu, click Save.
Important! When an IS document type is assigned to the input or output of a
service, you cannot add, delete, or modify the fields on that half of the Input/Output
tab.
Tip! You can also use a publishable document type to build a document reference or
document reference list field.
Click... To...
2 In the Name field, type the fully qualified name of the IS document type or select it
from the list next to Folder.
3 Click OK.
4 Type the name of the field.
5 Press ENTER.
Important! If you are creating a document reference or document reference list field
based on an IS document type, you cannot directly add, delete, or modify its
members on the Input/Output tab. To edit the referenced document or document
list, select it in the Navigation panel, lock it, and then edit its fields in the editor.
Tip! You can also add a document reference by dragging an IS document type from
the Navigation panel to the box below the Validate input or Validate output check boxes
on the Input/Output tab.
Field properties
On the Properties panel, the General category contains the properties of the field and the
Constraints category contains validation constraints for the field. (For more information
about specifying validation constraints, see “Applying Constraints to Variables” on
page 255.)
Creating a Specification
A specification is a “free‐standing” IS element that defines a set of service inputs and
outputs. If you have multiple services with the same input and output requirements, you
can point each service to a single specification rather than manually specify individual
input and output fields in each service.
Using specifications provides the following benefits:
It reduces the effort required to build each flow.
It improves accuracy, because there is less opportunity to introduce a typing error
when defining a field name.
It makes future specification changes easier to implement, because you can make the
change in one place (the specification) rather than in each individual service.
If you use a specification, keep in mind that:
Any change that you make to the specification is automatically propagated to all
services that reference that specification. (This happens the moment you save the
updated specification to the server.)
A specification wholly defines the input and output parameters for a service that
references it. This means that you cannot directly alter the service’s input and output
parameters through its Input/Output tab. (Developer displays the parameters, but does
not allow you to change them.) To make changes to the input and output parameters
of the service, you must modify the specification (which affects all services that
reference it) or detach the specification so you can manually define the parameters on
the service’s Input/Output tab.
You create a specification with Developer. You assign a specification to a service using the
Input/Output tab for the service.
To create a specification
1 On the File menu, click New.
2 In the New dialog box, select Specification, and click Next.
3 In the New Service Specification dialog box, do the following:
a In the list next to Folder, select the folder to which you want to save the
specification.
b In the Name field, type a name for the specification using any combination of
letters, numbers, and the underscore character.
Important! Developer does not allow the use of certain reserved words (such as for,
while, and if ) as names. If you specify a name that is a reserved word, you will
receive an error message. When this happens, use a different name or try adding a
letter or number to the name you specified to make it valid.
c Click Finish.
4 If you want this specification to reference another specification, do the following in
the editor:
a In Specification Reference field, type the specification’s name or click to select it
from a list.
b Skip the rest of this procedure.
Important! Typically, you do not build a specification by referencing another
specification. However, it is useful to do this in the situation where you will use
the specification with a group of services whose requirements are expected to
change (that is, they match an existing specification now but are expected to
change at some point in the future). Referencing a specification gives you the
convenience of using an existing specification and the flexibility to change the
specification for only that single group of services in the future.
5 If you want to reference an IS document type for the Input or Output half of the
specification, do the following:
a In the Input or Output field (depending on which half of the specification you want
to assign the IS document type to), type the IS document type name or click to
select it from a list. You can also drag an IS document type from the Navigation
panel to the box below the Validate input or Validate output check boxes on the
Input/Output tab. For information about creating IS document types, see “Creating
an IS Document Type” on page 233.
Tip! You can select a publishable document type or an IS document type to
define the input or output half of the specification.
b Proceed to the next step to specify the fields for the other half of the specification.
(If you assigned IS document types to both the Input and Output sides of this
specification, skip the rest of this procedure.)
Important! Once you assign an IS document type to the Input or Output side of a
specification, you cannot add, delete, or modify the fields on that half of the
Input/Output tab.
6 For each input or output field that you want to define, do the following:
a Select the half of the specification (Input or Output) where you want to define the
field by clicking anywhere in that half’s large white text box.
b Click on the toolbar and select the type of field that you want to specify.
c Type the name of the field and then press ENTER.
d With the field selected, set its properties and apply constraints on the Properties
panel (optional).
For details on setting field properties, see “Specifying Field Properties” on
page 247. For details on applying constraints, see “Applying Constraints to
Variables” on page 255.
e If the field is a document or a document list, repeat steps b–d to define each of its
members. Use to indent each member beneath the document or document list
field.
7 On the File menu, click Save.
1 Open the service to which you want to assign a specification.
2 Click the Input/Output tab.
3 In Specification Reference, type the fully qualified name of the specification, or click
to select it from a list.
Important! When a specification is assigned to a service, you cannot add, delete, or
modify the declared fields using that service’s Input/Output tab.
XML validation. The validation engine in webMethods Integration Server validates the
structure and content of an XML document against an IS schema.
The following sections provide information about performing each type of validation and
information about applying constraints to fields.
Note: When you create an IS document type from an XML Schema or a DTD, the
constraints applied to the elements and attributes in the original document are
preserved in the new IS document type. For more information about creating IS
document types, see “Creating an IS Document Type” on page 233.
1 Select the variable to which you want to apply constraints.
You can apply constraints to variables in IS document types, variables in a
specification, and variables declared on the Input/Output tab.
2 In the Constraints category on the Properties panel, do the following:
a If you want to require the selected variable to exist at run time, set the Required
property to True. If the existence of the variable is optional, set this property to
False.
b If you want to allow a variable to have a null value, set the Allow null property to
True. If you want the validation engine to generate an error when the variable has
a null value, set the Allow null property to False.
c If the selected variable is a document or document list and you want to allow it to
contain undeclared child variables, set the Allow unspecified fields property to True.
If this property is set to False, any child variables that exist in the pipeline but do
not appear in the declared document field will be treated as errors at run time.
d If the selected variable is a String, String list, or String table, and you want to
specify content constraints for the variable, click and then do one of the
following:
If you want to use a content type that corresponds to a built‐in simple type in
XML Schema, in the Content type list, select the type for the variable contents.
(For a description of these content constraints, see Appendix F, “Validation
Content Constraints”.) To apply the selected type to the variable, click OK.
If you want to customize the content type by changing the constraining facets
applied to the type, see “Customizing a String Content Type” on page 257.
If you want to use a simple type from an IS schema as the content constraint,
click the Browse button. In the Browse dialog box, select the IS schema
containing the simple type you want to apply. Then, select the simple type you
want to apply to the variable. To apply the selected type to the variable, click
OK.
If you want to customize the content type by changing the constraining facets
applied to the type, see “Customizing a String Content Type” on page 257.
Note: A content type corresponds to a simple type from an XML Schema
definition. All of the choices in the Content type list correspond to simple types
defined in XML Schema Part 2: Datatypes.
When you customize a type, you actually create a new content type. Developer saves the
changes as a new content type named contentType_customized. For example, if you
customize the string content type, Developer saves the new content type as
string_customized.
Note: When you edit a simple type definition in an IS schema, the changes are saved to
the selected type definition in the IS schema. The modifications affect any variable to
which the simple type is applied as a content type constraint. For more information
about editing a simple type definition, see “Editing a Simple Type in an IS Schema”
on page 231.
When customizing a content type, keep the following points in mind:
When you edit the constraining facets applied to a content type, you can only make
the constraining facet values more restrictive. The constraining facets cannot become
less restrictive. For more information about setting values for constraining facets, see
“Setting Constraining Facet Values” on page 233.
The constraining facets you can specify depend on the content type. For more
information about the constraining facets for each content type, see Appendix C,
“Supported Data Types” on page 405.
The customized content type applies only to the selected variable. To make changes
that affect all variables to which the content type is applied, edit the content type in
the IS schema. (String content types are simple types from IS schemas.) For more
information about editing simple types, see “Editing a Simple Type in an IS Schema”
on page 231.
1 Select the variable to which you want to apply a customized content type.
2 In the Constraints category on the Properties panel, click the Content type browse
button ( ) and then do one of the following to select the content type you want to
customize:
In the Content type list, select the content type you want to customize.
If you want to customize a simple type from an IS schema, click the Browse button.
In the Browse dialog box, select the IS schema containing the simple type. Then,
select the simple type you want to customize and apply to the variable.
3 Click the Customize button. Developer makes the constraining facet fields below the
Content type list available for data entry (that is, changes the background of the
constraining facet fields from grey to white). Developer changes the name of the
content type to contentType_customized.
4 In the fields below the Content type list, specify the constraining facet values you want
to apply to the content type. For more information about constraining facets, see
“Constraining Facets” on page 448.
5 Click OK. Developer saves the changes as a new content type named
contentType_customized.
Important! Developer throws exceptions at design time if the constraining facet values
for a content type are not valid. For more information about these exceptions, see
Appendix G, “Validation Errors and Exceptions”
Optional field.
Required field with content type constraint
Optional field with content type constraint
Note: Developer displays the ‡ symbol next to String, String list, and String table
variables with a content type constraint only. Developer does not display the ‡
symbol next to Object and Object list variables with a specified Java class constraint.
Object and Object lists with an applied Java class constraint have a unique icon. For
more information about icons for constrained Objects, see “Java Classes for Objects”
on page 407.
service executes. If you specify that you want to validate the outputs of the service, the
validation engine validates the service output values immediately after the service
executes. An input or output value is invalid if it does not conform to the constraints
applied to the input or output parameter.
For input/output validation, the services’s declared input and output parameters act as
the blueprint or model against which input/output values are validated. To effectively
use the input and output parameters as the blueprint for validation, you need to apply
constraints to the parameters. For information about applying constraints to variables,
see “Applying Constraints to Variables” on page 255. For information about declaring
service input and output parameters, see “Declaring Input and Output Parameters for a
Service” on page 122.
.
Note: The declared input and output parameters for a service are sometimes called the
signature of the service.
You can specify that you want to perform input/output validation for a service in the
following ways:
Input/Output tab. Set properties on the Input/Output tab to instruct the validation engine
in webMethods Integration Server to validate the inputs and/or outputs of the service
every time the service executes. If a client calls the service and the inputs are invalid,
the service fails and does not execute.
INVOKE step properties. Set up input/output validation via the INVOKE step properties
to instruct the validation engine to validate the service input and/or output only
when it is called from within another flow service. At run time, if the inputs and/or
outputs of the service are invalid, the INVOKE flow step that calls the service fails.
To determine which method to use, determine whether or not you want the service input
and output values validated every time the service runs. If you want to validate the input
and output values every time the service runs, specify validation via the Input/Output tab.
For example, if your service requires certain input to exist or fall within a specified range
of values, you might want the pipeline validated every time the service runs.
If the input and/or output values do not need to be validated every time the service
executes, set up validation via the INVOKE step properties. Specifying input/output
validation via the INVOKE step properties allows you to decide on a case‐by‐case basis
whether you want validation performed.
Note: If you specify input/output validation via the INVOKE step and an input or
output value is invalid, the service itself does not actually fail. The validation engine
validates input values before webMethods Integration Server executes the service. If
the service input is not valid, the INVOKE flow step for the service fails. Similarly, the
validation engine validates output values after webMethods Integration Server
executes the service. If the service output is not valid, the INVOKE flow step for the
service fails. Whether or not the entire flow service fails when an individual flow step
fails depends on the exit conditions for the service. For information about specifying
exit conditions, see “Using SEQUENCE to Specify an Exit Condition” on page 176.
1 Open the service for which you want to validate input and/or output every time the
service is invoked.
2 Click the Input/Output tab.
3 If you want the input of the service validated every time the service executes, select
the Validate input check box.
4 If you want the output of the service validated every time the service executes, select
the Validate output check box.
5 On the File menu, click Save.
1 In the flow editor, select the INVOKE step containing the service for which you want
Integration Server to validate input and/or output values.
2 In the General category on the Properties panel, do the following:
If you want to validate input to the service, set the Validate input property to True.
If you want to validate the output of the service, set the Validate output property to
True.
3 On the File menu, click Save.
Inputs to the
invoked service
will be validated.
Outputs of the
service will not be
validated.
Note: The validation engine in Integration Server performs document (IData object)
validation automatically when a document is published. The validation engine
validates the published document against the publishable document type.
Tip! If you want to validate only String, String list, or String table variables in the
pipeline, use the pub.schema:validatePipeline service. Define an IS document type that
contains the variables you want to validate and apply constraints to the variables.
Then use this IS document type as the blueprint for the pub.schema:validatePipeline
service. Only the variables in the IS document type will be validated. The validation
engine ignores other variables that exist in the pipeline at run time. (An IS document
type implicitly allows unspecified variables to exist at run time.)
determine what can and cannot be included in the pipeline. For more information about
applying constraints to variables, see “Applying Constraints to Variables” on page 255.
To validate the pipeline, invoke the built‐in service pub.schema:validatePipeline. This service
instructs the validation engine to compare the pipeline contents against a specified IS
document type. The pipeline is valid when it conforms to the structural and content
constraints applied to the IS document type. The pub.schema:validatePipeline service returns
a string that indicates whether validation was successful and an IData array (errors
variable) that contains any validation errors. For more information about the
pub.schema:validatePipeline service, see the webMethods Integration Server Built‐In Services
Reference.
Note: If an IS schema contains an element with a nillable attribute and the element
generated from the schema also contains the attribute xsi:nil=ʺtrueʺ, no document
validation is performed on the generated element.
.
.
.
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();
For additional information about pub.schema:validate and pub.schema:validatePipeline, see the
Schema services in the webMethods Integration Server Built‐In Services Reference.
Validation Exceptions
If you use the pub.schema:validate and pub.schema:validatePipeline services to perform data
validation, you can determine whether the service should succeed or fail if the data being
validated is invalid. You might want a service to succeed even if the data is invalid. In the
pub.schema:validate and pub.schema:validatePipeline services, the value of the failIfInvalid input
variable determines whether a service fails because of an invalid object.
If the pub.schema:validate and pub.schema:validatePipeline service fails, webMethods
Integration Server throws a validation exception. A validation exception is generated if
one of the following is true:
Errors are detected in the object (XML node, pipeline, or document (IData object))
that is passed (for example, null value).
The basic validation contract is violated (for example, a binary tree is passed instead
of a document (IData object) as expected).
You specify that the service should fail if the object to be validated (XML node,
pipeline, or document (IData object)) did not conform to the IS schema or IS
document type (for example, failIfInvalid = true). If this is the reason for the exception,
webMethods Integration Server inserts the validation errors into the exception
message.
1 Start webMethods Integration Server and open the Integration Server Administrator.
2 In the Settings menu of the navigation area, click Extended.
3 Click Edit Extended Settings. The server displays the Extended Settings screen.
4 In the text area under Extended Settings, type
watt.core.schema.maxOccursThresholdValue=value where value is the number you
want to use as the maxOccurs threshold.
5 Click Save Changes.
Note: For information about testing Broker/local triggers and publishable document
types, see the Publish‐Subscribe Developer’s Guide.
Testing Services
You can test any type of service (flow services or coded services) with Developer,
eliminating the need to build special clients simply for testing. It also allows you to easily
pass different sets of test data to your service, which makes it easy to test your service
under a variety of data conditions.
You can use Developer to test services in two ways:
From Developer. With this technique, Developer is the client. That is, Developer invokes
the service and receives the results.
From a browser. With this technique, Developer formulates the URL necessary to
invoke the service and passes that URL to your browser. Your browser actually
invokes the service and receives the results. When you develop services for browser‐
based clients (especially ones whose output will be formatted using output
templates) you will want to test those services at least once using this technique.
1 Open the service that you want to test.
2 On the Test menu, select Run. If you have not yet saved changes to the service,
Developer prompts you to save them.
3 If the service has input parameters, type the input values for each variable in the
Input dialog box or click the Load button to retrieve the values from a file. For more
information, see “Entering Input for a Service” on page 272.
4 If you want Developer to pass empty variables (variables that have no value) to the
service, select the Include empty values for String Types check box. When you select this
option, empty Strings are passed with a zero‐length value. If you do not select this
option, empty Strings are not passed to the service.
5 If you want to save the input values that you have entered, click Save. Input values
that you save can be recalled and reused in later tests. For more information about
saving input values, see “Saving Input Values to a File” on page 274.
6 Click OK. Developer invokes the service with the specified set of input values.
Notes:
If the service executes to completion, its results appear on the Results panel. For more
information about the Results panel, see “Viewing the Results of the Service” on
page 275.
If the service throws an exception, an error message displays. Click Details in the
message box to view the call stack and the state of the pipeline where the error
occurred. For more information about errors that occur while testing a service, see
“Run‐Time Exceptions” on page 277.
...and complex
documents and
document lists.
You can manually type your input values into the Input dialog box or, if you saved the
input values from an earlier test, you can load them from a file.
Note: If your service expects Object variables that do not have constraints assigned or
an Object defined as a byte[ ], you will not be able to enter those values in the Input
dialog box. To test these values in a service, you must also create a service that
generates input values for your service. Then you need to construct a test harness (a
flow service that executes both the service that produces the test data and the service
you want to test) and use that harness to test your service.
1 Open the service and execute it as described in “Testing Services from Developer” on
page 271 or “Testing Services from a Browser” on page 279.
2 For each variable listed in the Input dialog box, type an input value. If the service
takes complex variables such as a String lists, documents, or document lists, use the
following buttons to specify the variableʹs individual elements.
Add a row to the variable.
Insert a blank row above the currently selected row.
Add a column to the variable.
Delete the selected row from the variable.
Delete the selected column from the variable.
Note: When you enter values for constrained objects in the Input dialog box,
Developer automatically validates the values. If the value is not of the type specified
by the object constraint, Developer displays a message identifying the variable and
the expected type.
Note: You might want to consider creating an input file for each set of data that
you routinely test your service against. This will provide you with a ready‐made
set of test cases against which to verify the service when it is modified by you or
other developers in the future. Many sites establish a special directory on their
development server just for holding sets of test data that they generate in this
manner.
1 Open the service and execute it as described in “Testing Services from Developer” on
page 271 or “Testing Services from a Browser” on page 279.
2 Enter input values into the Input dialog box as described in “Entering Input for a
Service” on page 272.
3 When you are finished entering values, click Save.
4 In the Save File dialog box, specify the name of the file to which you want the values
saved.
Besides loading values that were saved from the Input dialog box, you can also load
values that were saved using pub.flow:savePipelineToFile service or the Save Pipeline
commands on the File menu. In addition, you can change values in the pipeline
during testing. For information about saving the state of the pipeline, see “Saving and
Restoring the Pipeline” on page 296. For information about modifying values in the
pipeline, see “Modifying the Current Pipeline” on page 295.
1 Open the service and execute it as described in “Testing Services from Developer” on
page 271.
2 When the Input dialog box appears, click Load. The Load File dialog box appears.
3 Select the file containing the input values that you want to load.
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...
The upper half of the Results panel displays all the variables in the pipeline. To view the
contents of a particular variable, you select the variable in the upper half. Its contents are
shown in the lower half.
When viewing the Results panel, keep the following points in mind:
The Results panel represents the contents of the pipeline.
The Results panel shows all variables placed in the pipeline by the service, not just
those that were declared in the service’s input/output parameters.
Variables that a service explicitly drops from the pipeline do not appear on the
Results panel.
You can browse the contents of the Results panel, but you cannot edit it directly.
You can save the contents of the Results panel to a file and use that file to restore the
pipeline at a later point. For additional information about saving and restoring the
contents of the Results panel, see “Saving and Restoring the Pipeline” on page 296.
If you run a service and an error occurs, results are not displayed in the Results panel.
However, you can click the Details button in the error message box to examine the
state of the pipeline at the point where the exception occurred.
When debugging a flow service in step mode, you can use the Results panel to
examine the state of the pipeline after each flow step. You can optionally load a
different pipeline or modify the existing pipeline between steps. For information
about loading a pipeline in the Results panel, see “Saving and Restoring the Pipeline”
on page 296. For information about modifying an existing pipeline, see “Modifying
the Current Pipeline” on page 295.
When you use a breakpoint or the Trace to Here command to halt execution of a flow
service, you can use the Results panel to examine the pipeline at that point where you
halted the flow. You may also optionally load a different pipeline or modify the
existing pipeline at this point. For information about loading a pipeline in the Results
panel, see “Saving and Restoring the Pipeline” on page 296. For information about
modifying an existing pipeline, see “Modifying the Current Pipeline” on page 295.
Variables whose object types are not directly supported by the Developer will appear
in the Results panel, but because Developer cannot render the values of such objects,
a value does not appear in the Value column. Instead, the Value column displays the
object’s Java class message.
Variables that contain com.wm.util.Table objects appear as document lists in the Results
panel.
A data definition (for example, the The copied elementʹs data definition.
Pipeline tab, the Input/Output tab, or a
document (IData object))
The name of an element The copied element’s name (and position if it
is a member of a complex element such as a
String table, document (IData object), or
document list (IData [ ])).
1 Display the Results panel and select the element that you want to copy. (When
copying elements from the lower half, you can select a group of contiguous elements
by pressing the SHIFT key and selecting the first and last element in the group that
you want to copy.)
2 On the Edit menu, click Copy.
3 Select the field into which you want to paste the information, then click EditPaste
After. (If the Paste command is not available, it indicates that the information cannot be
pasted into the selected field.)
Run-Time Exceptions
If a service that you run from Developer throws an exception, Developer reports the error
in a following message box.
You can click the Details button to display the call stack and the pipeline at the point
where the error occurred.
The Details button shows the call stack and the pipeline
Note: You can improve performance and memory usage in Developer by caching
elements, such as services and schemas. For details, see “Caching Elements” on
page 66.
This service
threw the
exception.
Now let’s assume that CHILD_B is a flow service that calls three Java services: CHILD_B1,
CHILD_B2, and CHILD_B3. If CHILD_B3 throws an exception, the call stack will look like this:
This service
threw the
exception.
Note that the call stack is LIFO based. That is, the top entry in the stack identifies the last
(that is, most recent) service invoked. The bottom entry identifies the parent service (the
one that you originally invoked from Developer). If the parent itself throws the exception,
it will be the only entry in the call stack.
Note: Services invoked from within a Java service are not reported in the call stack,
even if they throw the exception.
If you are developing services that will be invoked by browser‐based clients, particularly
ones whose output will be formatted using output templates, you will want to test those
services using the Run in Browser command to verify that they work as expected.
1 Open the service that you want to test.
2 On the Test menu, click Run in Browser. If you have unsaved edits, Developer prompts
you to save them.
3 If the service has input parameters, type the input values for each variable in the
Input dialog box or click the Load button to retrieve the values from a file. For more
information, see “Entering Input for a Service” on page 272.
Note: Only Strings and String lists are passed to the browser.
4 If you want to pass empty variables (variables that have no value) to the service, select
the Include empty values for String Types check box. When you select this option, empty
Strings are passed with a zero‐length value. If you do not select this option,
Developer excludes empty variables from the query string that it passes to the
browser.
5 If you want to save the input values that you have entered, click Save. Input values
that you save can be recalled and reused in later tests. For more information about
saving input values, see “Saving Input Values to a File” on page 274.
6 Click OK. Developer builds the URL to invoke the service with the inputs you have
specified, launches your browser, and passes it the URL.
If the service executes successfully, its results appear in your browser. (If an
output template is assigned to the service, the template will be applied to the
results before they are returned.)
If the service experiences an error, an error message is displayed in the browser.
1 Open the service that you want to test.
2 From the Test menu, select Send XML File. If you have unsaved edits, Developer
prompts you to save them.
3 In the Select Test Mode dialog box, specify whether you want the service to run in
Trace mode or Step mode and click OK.
4 In the Select File dialog box, select the XML file that you want to submit to this service
and click OK. Developer submits the file to the server, which parses it into a node
object and passes it to selected service.
If the service executes to completion, its results appear on the Results panel. For
more information, see “Viewing the Results of the Service” on page 275.
If the service experiences an error, an error message displays. Click Details in the
message box to view the call stack and the state of the pipeline where the error
occurred. For additional information about errors that occur while testing a
service, see “Run‐Time Exceptions” on page 277.
Note: You can only debug one flow service at a time.
Command Description
Trace Executes flow steps one after another to the end of the service and
visually marks steps as they execute. For information about using
this command, see “Using the Trace Tools” on page 284.
Trace to Here Executes flow steps one after another up to a specified point and
visually marks steps as they execute. For information about using
this command, see “Using the Trace Tools” on page 284.
Trace Into Executes flow steps one after another to the end of the service and
visually marks steps as they execute, including steps in child flows.
For information about using this command, see “Tracing into a
Child Flow” on page 285.
Step Executes the next flow step and then halts. For information about
using this command, see “Using the Step Tools” on page 286.
Step Into Opens a child flow or a MAP step so that you can debug the
individual flow steps within it. For information about using this
command, see “Stepping though a Child Flow” on page 287 and
“Using the Step Tools with a MAP Step” on page 288.
Important! The debug commands are only available for flow services. When a Java
service is selected, these commands are not available.
When you first enter debug mode, processing always starts from the first step in the flow
service. Completed steps are marked with a gray outline. A step that is “in process” or is
the next in line to be processed is marked with a green outline. When you step though a
flow service or you halt execution using a breakpoint or the Trace to Here command, the
green outline indicates which step will execute when you resume processing.
Tip! You can remove the gray and green trace lines by using the TestReset command.
Note, however, that this will also end your debugging session.
The following example shows a flow service that is being executed using the Step
command. As you can see, the BRANCH on ‘PaymentType’ step has three targets. The gray
outline shows which path was executed. The green outline indicates that BRANCH on
‘/AuthorizationCode’ is the step that will execute when the next Step command is performed.
The following actions do not reset a debugging session:
Setting breakpoints
Examining the contents of any of the other tabs associated with the service
Saving or restoring the contents of the Results panel
Trace to the end of the service without tracing child services Trace
(breakpoints are ignored in this mode)
Trace to a specified point in the service without tracing child Trace to Here
services (breakpoints are ignored in this mode)
Trace to the end of the service or the next breakpoint, including the Trace Into
paths of all child services that this service invokes
Note: To trace through a top‐level service, you must have Execute, Read, and List
access to the service. To trace through all the services within a top‐level service, you
must have Execute, List, and Read access to all services that the top‐level service
invokes. For more information about ACLs and the trace tools, see “ACLs and
Testing/Debugging Services” on page 111.
1 Open the service that you want to trace.
2 On the Test menu, click Trace.
If the service is already in debug mode, Developer traces the remaining steps,
starting from the current point of execution (the step outlined in green.)
If the service is not in debug mode, Developer starts the trace at the top of the
flow. If you have any unsaved changes, Developer prompts you to save those
changes before it starts the trace. If the service takes input, you will be prompted
for its input values.
1 Open the service that you want to trace.
2 In the editor, select the flow step up to which you want to trace. (Developer will trace
all steps up to, but not including, the one you select.)
Note: If the point to which you want to trace resides in a child of the service that
you are testing, you must use the breakpoint feature to trace to that point. For
information about setting breakpoints, see “Setting Breakpoints” on page 288.
3 On the Test menu, click Trace to Here.
If the service is already in debug mode, Developer starts at the current point of
execution (the step outlined in green) and traces to the selected step. If the
selected step is before the current point of execution, the trace starts at the top of
the flow.
If the service is not in debug mode, Developer starts the trace at the top of the
flow service and traces to the selected step. If you have any unsaved changes,
Developer prompts you to save those changes before it starts the trace. If the
service takes input, you will be prompted for its input values.
4 When Developer reaches the selected flow step, it halts. At this point, you may do any
of the following:
Examine the contents of the Results panel.
Modify, save, and/or restore the contents of the Results panel.
Use Step or Step Into to execute subsequent flow steps one at a time.
Select another step in the flow service and use Trace to Here to trace to that point.
Select Trace to trace the remainder of the service.
Select Reset to clear the debugging session and reset the starting execution point
to the top of the service.
1 Open the parent service that you want to test.
2 On the Test menu, click Trace Into.
If the service is already in debug mode, Developer starts the trace at the current
point of execution (the step outlined in green) and traces the service and its
children until it reaches a breakpoint or the end of the flow.
If the service is not in debug mode, Developer starts the trace at the top of the
flow and traces the service and its children until it reaches a breakpoint or the end
of the flow. If you have any unsaved changes, Developer prompts you to save
those changes before it starts the trace. If the service takes input, you will be
prompted for its input values.
Execute the current flow step (the one with the green outline) Step
Open a child flow so that you can debug the individual flow steps Step Into
within it
Return to the parent flow from a child that you have stepped into Step Out
Note: To step through a top‐level service, you must have Execute, Read, and List
access to the service. To step through all the services within a top‐level service, you
must have Execute, List, and Read access to all services that the top‐level service
invokes. For more information about ACLs and the step tools, see “ACLs and
Testing/Debugging Services” on page 111.
Note: When you step into a child flow, Developer displays the child flow in the editor.
Note that at any point while stepping through a flow service, you can do any of the
following:
Examine the contents of the Results panel.
Modify, save, and/or restore the contents of the Results panel.
Select a step in the flow service and use Trace to Here to trace to that point.
Select Trace to trace the remainder of the service.
Select Reset to clear the debugging session and reset the starting execution point to
the top of the service.
1 Open the service that you want to step through.
2 On the Test menu, click Step.
If the service is already in debug mode, Developer executes the current step (the
step outlined in green) and then stops.
If the service is not in debug mode, Developer enters debug mode and selects the
first step in the flow service. To execute that flow step, select Step again. If you
have any unsaved changes, Developer prompts you to save those changes before
it enters debug mode. If the service takes input, you will be prompted for its input
values.
1 Select the parent flow service and step or trace to the flow step that invokes the child
flow. See “To step through a flow service” on page 287 or “To trace to a specified
point” on page 285 if you need procedures for this step.
2 On the Test menu, click Step Into. Developer opens the child flow service and selects
(but does not execute) the first step.
3 On the Test menu, click Step to execute the first step in the child service. Repeat this
step for each flow step that you want to individually execute within the child.
4 If you want to return to the parent flow service without stepping through the entire
child, click Step Out from the Test menu. This command will trace the remaining steps
in the child flow, return to the parent, and then select (but not execute) the next step in
the parent flow.
Notes:
While you are debugging the child, you may use Trace to Here or set a breakpoint
to execute up to particular point in the child.
If you select Trace or Trace Into while you are debugging the child, Developer traces
the remaining steps in the child and returns to the parent automatically.
If you select Step on the last step in the child flow service, Developer
automatically returns you to the parent.
You can use Step Into to step into a child flow that is nested within a child that you
have stepped into.
If you select Step Into on a step that is not a flow service, Step is executed.
1 Select the parent service that contains the MAP step and then step or trace to the MAP
step. (That is, make the MAP step the current flow step. Developer indicates this by
outlining the step in green.) See “To step through a flow service” on page 287 or “To
trace to a specified point” on page 285 if you need procedures for this step.
2 On the Test menu, click Step Into. Developer selects on the Pipeline tab (but does not
execute) the first transformer in the MAP step.
3 On the Test menu, click Step to execute the first transformer. Repeat this step for each
transformer that you want to individually execute within the MAP step.
4 If you want to return to the parent without stepping through the entire MAP, select
Step Out from the Test menu. This traces the remaining transformers in the MAP,
returns to the parent, and selects (but does not execute) the next step in the parent
flow.
Notes:
If you select Trace or Trace Into while you are debugging the MAP, Developer traces
the remaining steps in the MAP and returns to the parent automatically.
If you select Step on the last transformer in the MAP, Developer automatically
executes that transformer and returns you to the parent flow.
You can use Step Into to step into a transformer that is a flow service.
If you select Step Into on a transformer that is not a flow service, Step is executed.
Setting Breakpoints
A breakpoint is a point in a flow service where you want processing to halt when you
execute that flow service with certain debug modes. Breakpoints can help you isolate a
section of code or examine data values at a particular point in the execution path. For
example, you might want to set a pair of breakpoints before and after a particular
segment of a flow so that you can examine the pipeline on the Results panel before and
after that segment executes.
When working with breakpoints, keep the following points in mind:
Breakpoints are not persistent. They exist only during the life of the Developer
session on the current server in which you set them. When you close Developer or
refresh the session on the current server, your breakpoints are cleared. (Note that
resetting debug mode does not clear your breakpoints.)
Breakpoints are also local to your Developer session on the current server.
Breakpoints that you set on your machine do not affect other developers or users who
might be executing or debugging services in which you have set breakpoints.
Breakpoints are only recognized when you execute a service with the Trace Into
command from Developer. If you execute a service using any of the other testing or
debugging commands, breakpoints are ignored.
If you are caching services by using the General area of the Options dialog box, and
your flow service has a breakpoint, you cannot clear the cache of the flow service until
the breakpoint is removed. For more information about caching, see “Configuring a
Service’s Use of Cache” on page 131.
To set a breakpoint in a service, you must have Read access to a service. However, if
the service is invoked within another service (a top‐level service) to which you have
Read access, you can set a breakpoint on the service within the top‐level service.
1 Open the flow service in which you want to set a breakpoint.
2 In the editor, select the step that will function as the breakpoint. (During debugging,
processing will halt immediately before this step).
3 On the Test menu, click Set Breakpoint. The step’s icon turns red, indicating that it is a
breakpoint.
1 Open the flow service in which you want to clear a breakpoint.
2 In the editor, select the breakpoint step.
Note: Transformers in a MAP step execute in an arbitrary order. You cannot assume an
order of execution. Consequently, some of the transformers in the MAP step might
execute before Developer reaches the breakpoint, even if the transformers appear
below the breakpoint on the Pipeline tab. Likewise, transformers above the breakpoint
might not execute before the breakpoint is encountered. (These will execute when you
resume tracing.) Executed transformers have a gray outline.
1 Open the flow service in which you want to set a breakpoint.
2 In the editor, select the MAP step containing the transformer that will function as the
breakpoint.
3 On the Pipeline tab, select the transformer that will function as the breakpoint. (During
debugging, processing will halt immediately before this transformer.)
1 Open the flow service in which you want to clear a breakpoint.
2 In the editor, select the MAP step that contains the transformer from which you want
to clear a breakpoint.
3 On the Pipeline tab, select the transformer from which you want to clear a breakpoint.
1 On the Test menu, click Breakpoints.
2 If you want to go to a specific breakpoint, select it and then click Go to Breakpoint.
3 If you want to clear a breakpoint, select it and then click Remove.
Note: Remember, breakpoints are not persistent. They only exist during the Developer
session on the current server in which you set them. When you refresh or close your
session on the current server, your breakpoints are cleared.
Disabling a step is useful in many testing and debugging situations. For example, you
might want to disable one or more steps to isolate a particular segment of a flow, similar
to the way you might “comment out” a section of source code in a program you are
testing.
Be aware that disabling a step sets a persistent attribute that is saved in the flow service.
Once you disable a step, it remains disabled until you explicitly re‐enable it with
Developer.
Important! The run‐time effect of disabling a step is the same as deleting it. Disabling a
key step or forgetting to re‐enable a disabled step can break the logic of a service
and/or cause the service to fail. Developer allows you to disable any step in a flow
service, but it is your responsibility to use this feature carefully.
1 Open the flow service that you want to edit.
2 In the editor, select the step that you want to disable.
3 On the Compose menu, click Disable Step.
The step dims, indicating that it is disabled.
1 Open the flow service that you want to edit.
2 In the editor, select the disabled step that you want to re‐enable.
3 On the Compose menu, click Enable Step.
Disabling Transformers
You can also use the ComposeDisable Step command to disable a transformer in a MAP
step. Transformers that you disable are not executed at run time. In fact, webMethods
Integration Server does not execute any of the links between pipeline variables and the
variables for a disabled transformer.
Disabled transformers appear dimmed when viewed in Developer.
Note: When you disable the MAP step, Developer automatically disables all of the
transformers in a MAP step
Important! The run‐time effect of disabling a transformer is the same as deleting it.
Disabling a transformer or forgetting to re‐enable a disabled transformer can break
the logic of a service and/or cause the service to fail. Although Developer allows you
to disable any transformer or step in a flow service, use this feature carefully.
1 Open the flow service that you want to edit.
2 In the editor, select the MAP step containing the transformer that you want to disable.
3 On the Pipeline tab, select the transformer you want to disable.
4 On the Compose menu, click Disable Step.
The transformer dims, indicating that it is disabled.
1 Open the flow service that you want to edit.
2 In the editor, select the MAP step containing the disabled transformer that you want
to enable.
3 On the Pipeline tab, select the disabled transformer that you want to enable.
4 On the Compose menu, click Enable Step.
1 Open the flow service that you want to edit.
2 In the editor, select the INVOKE or MAP step that contains the link with the condition
you want to disable.
3 On the Pipeline tab, select the link with the condition that you want to disable.
4 In the General category of the Properties panel, set the Evaluate copy condition property
to False.
1 Open the flow service that you want to edit.
2 In the editor, select the INVOKE or MAP step containing the link with the condition
you want to enable.
3 On the Pipeline tab, select the link with the condition that you want to enable.
4 In the General category of the Properties panel, set the Evaluate copy condition property
to True.
You can view a pipeline file with an ordinary text editor. When saving the pipeline, keep
the following points in mind:
Only XML‐codable variables are saved. This includes, Strings, String lists, String
tables, documents, and document lists. Variables that are not XML codable are not
saved.
Empty variables and null variables are saved.
1 Display the Results panel and click anywhere within it.
2 Right‐click and select one of the following commands:
To… Select this command…
Note: If you intend to use the pipeline file to dynamically
restore the pipeline using pub.flow:restorePipelineFromFile,
use Save Pipeline to Server to save the file to the server (see
below).
3 Depending on your action in the previous step, do one of the following:
If you selected… Do this to specify the file name…
Key Description
filename A string that specifies the name of the file to which you want the
file saved. If you do not specify a fully qualified path, the file is
saved relative to IntegrationServer_directory\pipeline.
4 Save the service. (If you are using your own IDE, you will need to recompile the
service, reregister it on the Integration Server, and reload its package.)
5 Execute the service.
For additional information about pub.flow:savePipelineToFile, see the webMethods Integration
Server Built‐In Services Reference.
1 Display the Results panel. (If you simply want to inspect a saved pipeline, create a
new, empty flow service and display its Results panel.)
2 Right‐click and select one of the following commands:
To... Select...
3 Depending on your action in the previous step, do one of the following:
3 Set the following parameters:
Key Description
filename A String that specifies the name of the pipeline file. If you do not
specify a fully qualified path, the file is assumed to be relative to
IntegrationServer_directory\pipeline. For example, if you set
filename to “badPipeline.xml”, restorePipelineFromFile expects to
find that file in
IntegrationServer_directory\pipeline\badPipeline.xml.
merge A String that specifies whether you want the contents of the file
to replace or be merged with the existing pipeline.
Set merge to... To...
false Replace the existing pipeline with the one
from the file.
true Merge the contents of the file into the existing
pipeline.
4 Save the service. (If you are using your own IDE, you will need to recompile the
service, reregister it on webMethods Integration Server, and reload its package.)
5 Execute the service.
For additional information about pub.flow:restorePipelineFromFile, see the webMethods
Integration Server Built‐In Services Reference.
detailed log. For more information about the available logging levels, see the webMethods
Logging Guide.
The following example shows the startup command you would use to start the server at
the trace debug level.
If you do not explicitly set the debug switch when you start the server, the default value
specified in the watt.debug.level parameter is used. The default value of
watt.debug.level is Info.
Once you start the server, the debug level is set. When the server is running, you can
change the debug level using the Integration Server Administrator. If you do not know
the debug level under which your webMethods Integration Server operates, see your
webMethods Integration Server administrator.
Instead of running the entire Integration Server at a higher debug level, you can increase
the logging level for a specific facility in Integration Server. For example, you might set
the logging level for the Services facility to Trace. For more information about
configuring server logging, see webMethods Logging Guide.
Important! Debug levels above Info produce lots of detail and can quickly generate an
extremely large log file. You should not run your server at the Debug or Trace levels
except for brief periods when you are attempting to troubleshoot a particular issue.
You may also optionally redirect server log messages to the console instead of a file
using the –log none startup switch. For more information about this switch and
debug levels, see “Starting the webMethods Integration Server” in the webMethods
Integration Server Administrator’s Guide.
value of a particular variable in the log file so you can examine it after the service
executes.
The following example shows two progress messages (highlighted) that were posted to
the server log using pub.flow:debugLog.
To use pub.flow:debugLog, take the following general steps:
1 Invoke pub.flow:debugLog at the point where you want the service to write a message to
the server log.
2 Set the following parameters:
Key Description
message A String that specifies the message that you want written to server log.
This can be a literal string that you assign to message, however, for
debugging purposes, it is often useful to link this parameter to a
pipeline variable whose run‐time value you want to capture.
function Optional. A String that identifies your service. The String you specify
will appear in the second column of the message that debugLog writes to
server log. The purpose of this label is to identify which component
posted the message to the log.
If you do not assign a value to function, debugLog omits the label.
However, keep in mind that assigning a value to function will make it
easier for you to locate your service’s message when you examine the
log file. Although you can assign a text string of any length to function,
only the first 6 characters appear in the log.
level Optional. A String specifying the debug levels under which this
message is to be posted to the log. If the server is running at a debug
level lower than the value set in level, the message is not put into the
log file.
If you do not specify level, the Fatal level is assumed, which means that
the message is posted to the log file regardless of which debug level the
server is running at. For more information about debug level, see
“Server Debug Levels” on page 301.
3 Save the service. (If you are using your own IDE, you will need to recompile the
service, reregister it on webMethods Integration Server, and reload its package.)
4 Execute the service.
For additional information about pub.flow:debugLog, see the webMethods Integration Server
Built‐In Services Reference.
To use pub.flow:tracePipeline, take the following general steps:
1 Invoke pub.flow:tracePipeline at the point where you want the service to dump a copy of
the pipeline to the server log.
2 Set the following parameters:
Key Description
3 Save the service. (If you are using your own IDE, you will need to recompile the
service, reregister it on webMethods Integration Server, and reload its package.)
4 Execute the service. For additional information about pub.flow:tracePipeline, see the
webMethods Integration Server Built‐In Services Reference.
Basic Concepts
In addition to using the built‐in services that webMethods Integration Server provides,
you can create customized services in a variety of program languages. This allows you to
create a library of custom code that can be accessed and executed from a flow service or
from a client application.
This chapter describes how to create your own services using Java, C/C++, and Visual
Basic.
Important! Java is the native language for services. When you create services in other
languages, you must wrap them to appear as a Java class to webMethods Integration
Server.
When a service is invoked, webMethods Integration Server passes the IData object to it.
The service extracts the actual input values it needs from the elements within the IData
object. For example:
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;
}
A service returns output by inserting it into an IData object. Any information that is
produced by the service and must be returned to the calling program must be written to
the IData object. For example:
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;
}
For more information about using the IDataFactory class, see the data package in the
webMethods Integration Server Java API Reference at:
Developer_directory\doc\api\Java\index.html.
Before you create a Java service, you must:
Make sure the package in which you want to create the service already exists. If the package
does not already exist, use Developer or the Integration Server Administrator to
create it. For details, see “Creating a Package” on page 72.
Make sure the folder in which you want to create the service already exists. If the folder does
not already exist, use Developer to create it. For details, see “Creating New Elements”
on page 41.
Make sure that all Java and C services are unlocked or locked by you in the folder in which you
want to create the new service. For details, see “Locking Java and C/C++ Services” on
page 91.
Important! All Java services that belong to the same folder reside in the same Java class
file. This class has the same name as the folder.
Developer
automatically
generates required
code for you.
The required code at the top of the Java service editor defines a static and final method
with a single input parameter: an IData object. The block of required code at the bottom
returns the pipeline to the caller.
When you build a Java service, you type (or paste) your code in the text box in the Java
service editor. The following example shows a service that gets two values from the
pipeline and uses them to compute a sales tax. It puts the computed tax into the pipeline.
You use the Java service editor to write the body of your service
Type your
code in here.
You use the Shared tab to specify the common attributes of the class
The Extends field allows you to specify a super class for the implementation. You are not
required to specify a super class.
Note: It is useful, but not necessary, to extend the class
com.wm.app.b2b.server.Service. This class includes static methods for various
common tasks, like retrieving the current session ID and formatting error messages.
The Implements field specifies the names of Java interfaces that you want to implement in
the extended class.
The Imports field specifies the names of additional Java packages whose classes are
available to the current class. When you create a Java service with Developer, several Java
packages are automatically added to the import list.
The Source field allows you to define global variables and methods that are shared by all
services in the current folder. This is useful for building shared data structures and
supporting functions that are not intended to be exposed as services. For example, you
might use the Source field to define an account table and the methods to used to access it
for a set of services that create, get, and delete account information.
Note: Because services are implemented as static methods, most shared code is usually
static as well.
1 On the File menu, click New.
2 Click Java Service and click Next.
3 In the New Java Service dialog box, next to Folder, select the folder into which you
want to save this service.
4 In the Name field, type a name for the service.
5 Click Finish.
6 If you know the set of inputs and outputs your program uses, specify these using the
Input/Output tab.
Note: You can use Developer to automatically generate Java code that gets and
puts those input and output values in the pipeline. For more information about
automatically generating Java code, see “Generating Java Code from Service
Input and Output Parameters” on page 315.
7 Type the code for your service at the top of the Java service editor. For information
about Java classes provided with webMethods Integration Server, see the webMethods
Integration Server Java API Reference in Developer_directory\doc\api\Java\index.html.
8 If you want to make additional methods and/or structures available to the service,
complete the following fields on the Shared tab.
Extends The name of the superclass (if any) of which this class is an
extension. If you specify a superclass, type its Java class name
(fully qualified if necessary).
Implements The names of interfaces within the superclass that this class
implements. Take the following steps to specify each interface that
you want to implement:
Click to add a new row to the list.
Type the name of a valid Java class name (fully qualified if
necessary). You do not need to type the “implements”
keyword.
Imports The names of Java packages that this class imports. Take the
following steps to specify each package that you want to import:
Click to add a new row to the list.
Type the name of a valid Java class name (for example,
com.wm.util.Table) or a package import specification (for
example, java.util.*). You do not need to type the “import”
keyword.
Source Data structures, methods, and other Java code that you want to
make available to all services in this folder.
9 When you finish specifying your code in the Java service editor and on the Shared tab,
click on the toolbar to save and compile the service.
10 If Developer cannot compile the service because the Integration Server to which you
are connected cannot find a Java compiler, Developer displays an error message. Do
the following to ensure the Integration Server can locate the Java compiler:
a Ensure that a Java compiler is installed on the same machine as the Integration
Server.
b Add the location of the Java compiler to the system path of the machine where the
Integration Server is installed.
c Restart the Integration Server.
For example, if the Input/Output tab for the service defines the following variables as input
and output:
State String
Amount String
Tax String
Developer will generate the following Java code for your service:
// 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();
When Developer generates code from the service input/output parameters, it puts the
code on the Clipboard. From there, you can paste it into your program (at the top of the
Java service editor or in your own IDE) and modify it as necessary.
Note: webMethods Integration Server returns everything that your service puts into
the pipeline, regardless of what is declared as its input/output parameters. Declaring
a serviceʹs input and output parameters does not filter what variables the service
actually receives or returns at run time. It simply provides a formal description of
what the service requires as input and produces as output.
1 Open the Java service for which you want to generate code (if you are creating the
Java service in your own IDE, use Developer to create a new, empty Java service that
you will use only for the purpose of declaring a set of input/output parameters).
2 Click the Input/Output tab and define the inputs and outputs for this service if they are
not already specified. For more information about defining inputs and outputs for a
service, see “To declare input and output parameters for a service” on page 126.
3 If you want to generate code for a subset of the variables on the Input/Output tab, select
those variables.
4 On the Tools menu, click Generate Code.
5 On the Code Generation dialog box, select For implementing this service and click Next.
6 Specify the following options.
Specification Whether you want to generate code for the input variables, the
output variables, or both.
Which fields? Whether you want to generate code for all variables in the
Input/Output tab or just the selected variables.
7 Click Finish. Developer generates code and places it on the Clipboard.
8 Paste the contents of the Clipboard into your source code.
The ns directory contains information about the services in that package. An “entry” in
the namespace directory corresponds to a service or a folder. The contents of each entry
depend on what kind of entry it is.
Service entries contain information about properties of the service (for example,
statelessness), the input and output parameters of the service (if they have been
defined), and Java or XML source if the source is available for that service.
Folder entries contain information about the folder. This information is usually limited
to Java source for the services in that folder, if available.
For Java services, information about the service is stored in the namespace directory.
However, the compiled code for that service (that is, the class file) is stored in the code
subdirectory. The following shows the directory path to the class files in the purch
package.
IntegrationServer_directory\packages\purch\code\classes\recording\
accounts.class
When you use Developer to build a Java service, it automatically updates and maintains
the folder and service information in the namespace. However, if you build a Java service
in your own IDE, you must use a utility called jcode to compile your service and generate
the necessary files in the namespace.
Important! Although you may want to examine the contents of the namespace
directories on your webMethods Integration Server, do not modify this information
by hand. Only modify this information using the appropriate webMethods tools or
utilities. Inappropriate changes, especially to the ns directory of the WmRoot
package, can disable your server.
Note: Services can throw ServiceException. Do not call Service.throwError.
Additionally,
Your Java class must import the following Java packages.
com.wm.data.*;
com.wm.app.b2b.server.ServiceException;
com.wm.app.b2b.server.Service;
Your Java class must be public.
For performance reasons, it is also recommended that you make your class final.
Stage 2 Specify the input and output parameters (signature) of the service. During this
stage, you define the service’s inputs and outputs (if you know these). You
can use Developer to generate the input and output code that you can
paste into your program (see “Generating Java Code from Service Input
and Output Parameters” on page 315).
Stage 4 Saving and compiling your code using jcode (optional). During this stage, you
can make your source code available for editing by Developer by using
the jcode utility. For information, see “Commenting Code for the
webMethods Integration Server” on page 320.
You use similar tags to mark the beginning and end of other components in your source
code. For a complete example, see “jcode Example” in Appendix E, “jcode tags”. For
additional information about the jcode utility, see the next section “Using the jcode
Utility”.
Important! Before you can compile a service using jcode, you must set the environment
variable IS_DIR to point to the directory in which webMethods Integration Server is
installed.
Make Mode
You use this mode to examine source files for one or more folders in a package and
compile those that have been modified since they were last compiled. The jcode utility
will report which files were compiled, as well as any errors that were encountered during
the process.
To make all the code in a package, type the following on the command line:
jcode makeall Package
To compile source files, the jcode utility invokes the JDK Java compiler, javac using the
following command:
javac –classpath pathName –d classDir fileList
Where pathName is the classpath to use for the compile, classDir is the destination
directory for the compiled classes, and fileList is a list of the names of source files to
compile.
If you do not have the JDK installed, or you want to use another compiler, you can set
webMethods Integration Server’s watt.server.compile property to a new command line
(using the arguments described above). For instance, to use IBM’s jikes, you would set
this property to:
jikes +E –nowarn –classpath pathName –d classDir fileList
Fragment Mode
You use this mode to update the Java code fragments and service signatures (input and
output parameters) in the namespace based on the jcode tags in the source code file. The
original source file is not modified, but namespace information is updated and the source
code for the service becomes available through Developer.
To fragment all the code in a package, type the following on the command line:
jcode fragall Package
To fragment only the code for a single folder (that is, a single Java source file), type the
following on the command line:
jcode frag Package Folder
Composite Mode
Composite mode is the opposite of fragment mode. You use this mode to build a source
file based on the code fragments currently defined in the namespace.
Important! The existing source file, if there is one, is overwritten by the source file
produced by jcode. User locks in Developer will not prevent this, since the jcode
utility operates independently of locking functionality.
To construct a source file based on the current information in the namespace, type the
following on the command line:
jcode comp Package Folder
Important! If your Java source code contains any non‐ASCII characters, set the property
watt.server.java.source=Unicode | UnicodeBig | UnicodeLittle. The default value
is file.encoding. When Unicode is set, the compile command line specified in the
property watt.server.compile.unicode is used. The default value of this property is
“javac -encoding Unicode -classpath {0} -d {1} {2}”.
To update (make and frag) all the code in all packages on webMethods Integration
Server, type the following at the command line:
jcode upall
To force a make and frag on all packages on webMethods Integration Server, type:
jcode hailmary
Note: If you are running the Integration Server as an NT service, you must
complete one of the following:
Set the Windows system environment variable PATH to include
IntegrationServer\lib
‐OR‐
Copy the wmJNI.dll and wmJNIc.dll files located in IntegrationServer\lib
to the
IntegrationServer directory
where IntegrationServer is the directory in which you installed the
Integration Server.
1 On the File menu, click New.
2 Click C Service and click Next.
3 In the New C Service dialog box, in the list next to Folder, select the folder into which
you want to save this service.
4 In the Name field, type a name for the service and click Next.
5 Select the platform that describes the machine on which your webMethods
Integration Server is running (Developer needs to know this in order to build the
right make file). Click Next.
6 Select the specification for this service.
7 Click Finish.
Developer generates all the Java code needed to successfully call your C program. You
may add your own custom code to the C service editor or its Shared tab if you want to
execute any special procedures before or after the C program is called, but other than
that, this service contains everything you need.
The C service editor contains code that calls the Java wrapper for the C program
The Shared tab contains code that loads the library containing the C program
The Input/Output tab declares the input/output parameters for the service
The names of the files will match the service name you specified in Developer.
1 Locate the source code and make files.
2 Copy the source code file to a new file (in the same directory) with the following file
name:
serviceNameImpl.c
For example, if your service name is PostPO, you would copy PostPO.c to PostPOImpl.c.
You create the program in the serviceNameImpl.c file, not the original file. This is the
file in which the make file expects to find your source code. (This step is taken to
maintain a copy of the original source file to which you can refer, or revert back to,
during your development.)
3 Edit the serviceNameImpl.c file as necessary to build your service.
This file will contain instructive comments that will guide your development. You can
also refer to webMethods C API for information about how to use the webMethods
C/C++ API to make the data in your service available to other services. This file is
located in Developer_directory\doc\api\c\index.html.
4 Edit the make file to customize it for your development environment. Set the
following path settings:
Set... To...
JDKDIR To the directory that contains the Java Development Kit.
SEVRDIR The directory in which webMethods Integration Server is
installed.
Important! The source code file serviceName.c contains code based on the
specification you selected for the service. If you edit the specification, you need to
regenerate the source code file. Developer does not update the serviceName.c file
automatically. For more information about generating source code files for a
C/C++ service, see “Generating Files for a C/C++ Service” on page 324.
5 After you finish coding your service, run your make file to compile it. Following is a
typical make command:
make –f SalesTax.mak
The make file compiles your program and puts the finished DLL in the code\libs
directory in the package in which the service resides (if this directory does not exist
when you run the make file, your program will not compile successfully).
6 Once your program compiles successfully, restart webMethods Integration Server to
reload the code\libs directory. This makes the service available for execution and
allows you to test it with Developer. For details on testing, see Chapter 11, “Testing
and Debugging Services”.
Requirements
To use webMethods Integration Server with COM or DCOM, your webMethods
Integration Server must be running Java Virtual Machine 1.2 or later.
Important! If you modify Visual Basic code intended for use with webMethods
Integration Server libraries, do not use the debug mode in the Visual Basic
development environment to test your code. (The debugger does not maintain
references to webMethods Integration Server libraries.) Instead, use a logging feature
in your development environment to test the code.
Note: The WmWin32 package is deprecated for Integration Server 7.1.
The service will return a reference to the object called pDispatch or throw an error if the
object cannot be created.
Tip! The WmWin32 package is installed with the Integration Server on Microsoft
Windows platforms but, by default, is not enabled. To view the package and access its
services within Developer, first enable it using the Integration Server Administrator.
Name Description
pDispatch An object reference previously obtained by the call to createObject or
obtained in the result value of a previous call to invoke.
dispName The name of the COM method or property that you want to invoke.
accessType Optional. The type of operation (METHOD, GET, PUT, PUTREF) to be
performed on dispName. If you are invoking a DCOM object, always set
accessType to GET. Incorrect setting of this parameter will cause the
invoke to fail.
If you are unsure whether a dispName is a method or property, examine
the component’s type library using OLEVIEW or a Microsoft
development environment.
params Optional. An object array of parameters. This is exposed in Developer as
an array of Strings for usability (because Objects cannot be manipulated
in Developer), but is in reality an Object array. If you need to pass
complex or native types, you may have to create this value within your
own service.
If the invocation is successful, the return value is contained in “result.” If the result is an
object variable, it can then be the target of subsequent calls to invoke by linking the result
to pDispatch in the next invoke.
Basic Concepts
webMethods Developer enables you to automatically generate client code in a variety of
languages and for several environments. Client code is application code that invokes a
service on a webMethods Integration Server. It typically performs the following basic
tasks:
Prompts the user for input values (if your service takes input)
Places the inputs into an input document (if your service takes input)
Opens a session on webMethods Integration Server
Invokes a service
Receives output from the service
Closes a session on webMethods Integration Server
Displays the output to the user
The client code that Developer generates can serve as a good starting point for your own
development.
Assumptions
webMethods Integration Server is running.
A fully functional JDK is installed. If you are using the JVM that was installed with
the Integration Server, no further action is needed. If you are using a different JVM,
do the following to obtain the files the Integration Server needs to support signed
libraries:
If your run-
time JDK is... Do the following...
JDK 1.4.* Ensure that the unlimited strength jurisdiction policy files
(local_policy.jar and US_export_policy.jar) are installed as part of
your JVM installation.
If these files are not installed, download them as follows:
If you are running the Sun JDK 1.4.*, download the files from
http://java.sun.com/j2se/1.4.1/download.html/.
If you are running the IBM JDK 1.4.*, download the files from
http://www‐106.ibm.com/developerworks/java/jdk/security/.
JDK 1.5.* Ensure that the unlimited strength jurisdiction policy files
(local_policy.jar and US_export_policy.jar) are installed as part of
your JVM installation.
If these files are not installed, download them as follows:
If you are running the Sun JDK 1.5.*, download the files from
http://java.sun.com/javase/downloads/index.jsp.
If you are running the IBM JDK 1.5.*, download the files from
http://www‐106.ibm.com/developerworks/java/jdk/security/.
You are using one of the cryptographic service providers (CSPs) that webMethods
Integration Server provides (Sun, IBM, Entrust, or IAIK). If you are using a different
provider, the libraries supplied by that provider must be digitally signed.
Your classpath consists of at least the following:
webMethods_directory\common\lib\wm-isclient.jar
webMethods_directory\common\lib\ext\mail.jar
If you want to use any classes in the Entrust Toolkit, the classpath must contain the
following:
webMethods_directory\common\lib\ext\enttoolkit.jar
Limitations
When Developer generates client code, it ignores input or output variables that are of
type Object or Object list. Client code is not generated for these variables.
When Developer generates client code, Developer replaces any space in a variable
name with an underscore.
The client code that Developer generates does not support multiple input or output
variables with the same name.
If you want to override these limitations, you will need to modify the client code that
Developer generates.
Procedure
Use the following procedure to generate Java client code that invokes a service:
1 Open the service for which you want to generate client code.
2 On the Tools menu, click Generate Code.
3 In the Code Generation dialog box, select For calling this service from a client, and then
click Next.
4 In the Language field, select Java, and then click Next.
5 Specify the directory where you want Developer to place the generated client code.
Either select an existing directory or type the path for a new directory. If you type the
path for a new directory, Developer creates the directory.
6 Click Finish.
Developer generates the file that contains the Java client code (ServiceName.java) and
a Readme.txt file. The Java client code is written to the hard disk in ISO8859_1, the
character set in which the file is encoded.
Modify the generated client code to meet your site’s needs. You can update the client
code to invoke built‐in services and to use the provided Java API. For information
about the built‐in services that are available, see the webMethods Integration Server
Built‐In Services Reference. Documentation for the Java API can be found at
Developer_directory\doc\api\Java\index.html.
To complete your client application, refer to the Readme.txt file located in the same
directory as your client code.
Readme.txt A file that contains information and instructions for the Java client
code. Refer to this file for information about compiling and
running the Java client application.
ServiceName.java An example file, encoded in ISO8859_1, that contains the
application code for the Java client. The application code includes
a rudimentary user interface that uses the classes in the
FolderName directory. It is not intended for use “as is” in custom
applications.
Assumptions
webMethods Integration Server is running.
A platform that has the C/C++ compiler (for example, GCC) is installed. webMethods
generates code for the following platforms: Windows, Solaris, HP‐UX, Linux, AIX.
The wm‐isclient.jar file is in the classpath for Developer. The client.jar file is a
webMethods file that is located in the webMethods_directory\common\lib directory.
The Make facility is installed.
JDK 1.1.x is installed (if you intend to use the C libraries provided with Integration
Server and Developer).
Important! The provided C libraries are built using JDK 1.1.7. If you want to use a
different version of the JDK to compile C/C++ services, you need to rebuild the C/C++
libraries with that JDK and then replace the old library files with the rebuilt ones. For
more information about rebuilding the C libraries, see the README installed with
the C/C++ SDK.
To rebuild the C libraries, you need use the C/C++ SDK. The C/C++ SDK is not
installed by default. To install the C/C++ SDK, select it from the list of installable
components during installation.
Limitations
The client code that Developer generates does not support multiple input or output
variables with the same name.
When Developer generates client code, Developer replaces any space in a variable
name with an underscore.
If you want to override these limitations, you will need to modify the client code that
Developer generates.
Procedure
Use the following procedure to have Developer generate C/C++ client code that invokes a
service:
1 Open the service for which you want to generate client code.
2 On the Tools menu, click Generate Code.
3 In the Code Generation dialog box, select For calling this service from a client; then click
Next.
4 In the Language field, select the C/C++ platform for which you are creating client code.
Click Next.
5 Identify the directory where you want Developer to place the generated client code.
Either select an existing directory or type the path for a new directory. If you type the
path for a new directory, Developer creates the directory.
6 Click Finish.
Developer generates the file that contains the C client code (ServiceName.c), a file that
contains compiling settings (ServiceName.mak), and a CReadme.txt file.
Modify the generated client code to meet your site’s needs. You can update the client
code to invoke built‐in services and to use the webMethods C API. For information
about the built‐in services that are available, see the webMethods Integration Server
Built‐In Services Reference. For documentation about the C API, see
Developer_directory\doc\api\C\index.html.
To complete your client application, refer to the CReadme.txt file located in the same
directory as your client code.
CReadme.txt A file that contains information and instructions for the C client
code. Refer to this file for information about compiling, running,
and deploying your C/C++ client application.
ServiceName.mak A file that contains compiling settings for the C/C++ client. Be sure
to update this file with the correct settings for your environment.
ServiceName.c An example file that contains the C/C++ client code. It is not
intended for use “as is” in custom applications.
Assumptions
webMethods Integration Server is running.
Visual Basic Version 6 is installed.
webMethods7 Type Library is installed.
Note: The webMethods7 Type Library is a COM object that Visual Basic uses to
interact with webMethods Integration Server. The webMethods7 Type Library is
automatically installed when you install Developer.
Environment Setup
Your system PATH environment variable must include the following directory:
webMethods7\jvm\win150\jre\bin\client
Limitations
The client code that Developer generates supports only input values and output
values of type String, String list, and String table.
The client code that Developer generates does not support multiple input or output
variables with the same name.
When Developer generates client code, Developer replaces any space in a variable
name with an underscore.
If you want to override these limitations, you will need to modify the client code that
Developer generates.
Procedure
Use the following procedure to have Developer generate Visual Basic client code that
invokes a service.
1 Open the service for which you want to generate client code.
2 On the Tools menu, click Generate Code.
General Files
ServiceName.vbp The Visual Basic project file.
ServiceNameReadme.txt The file that contains information and instructions for the
Visual Basic client code. Refer to this file for information
about deploying your Visual Basic client application.
frmArrayInput.frm Contains layout and code that is used if any of the input
values for the service are of type String list.
frmOutput.frm Contains layout and code that is used when the service
returns output. It also contains the Setup, Invoke, and Exit
buttons.
frmSetup.frm Contains layout and code that prompts for the server
properties for the webMethods Integration Server on
which the service to execute resides.
frmStringInput.frm Contains layout and code that is used if any of the input
values for the service are of type String.
frmTableInput.frm Contains layout and code that is used if any of the input
values for the service are of type String table.
wmSampleLib.bas Contains code that is specific to the sample template that
Developer generates.
ServiceName.bas An example file that illustrates how to use the service class
in an application. This module is dependent on objects in
the project template that Developer provides. It is not
intended for use “as is” in custom applications.
ServiceName.cls The service object. You include this object in your own
project.
File Containing the Code that Interacts with webMethods Integration Server
wmVBConnection.bas Code used as a layer of abstraction to interact with
webMethods Integration Server.
Assumptions
webMethods Integration Server is running.
Excel 97 or Excel 2000 is installed.
webMethods7 Type Library is installed.
Note: The webMethods7 Type Library is a COM object that Visual Basic uses to
interact with webMethods Integration Server. The webMethods7 Type Library is
automatically installed when you install Developer.
Limitations
The client code that Developer generates only supports input values of type String
and output values of type String, String list, and String table.
The client code that Developer generates does not support multiple input or output
variables with the same name.
When Developer generates client code, Developer replaces any space in a variable
name with an underscore.
If you want to override these limitations, you will need to modify the client code that
Developer generates.
Procedure
Use the following procedure to have Developer generate Excel client code that invokes a
service.
1 Open the service for which you want to generate client code.
2 On the Tools menu, click Generate Code.
3 In the Code Generation dialog box, select For calling this service from a client, and click
Next.
4 In the Language field, select Excel 97/2000, and click Next.
5 Identify the directory where you want Developer to place the generated client code.
Either select an existing directory or type the path for a new directory. If you type the
path for a new directory, Developer creates the directory.
6 Click Finish.
Developer generates several files, including the serviceNameReadMe.txt file. This file
contains detailed information about all generated files.
7 Copy the wmXLTemplate.xls file that Developer provides to the directory that
contains the client code that Developer generated. The wmXLTemplate.xls file is
located in the Developer_directory\support\Excel directory.
8 Open the wmXLTemplate.xls file. When prompted to indicate whether you want to
enable macros, select Enable Macros.
9 Follow the instructions in the wmXLTemplate.xls file to complete your client
application. See the ServiceNameReadMe.txt file for information about deploying your
client application.
ServiceNameReadMe.txt A file that contains information and instructions for the
Visual Basic client code. Refer to this file for information
about deploying your Visual Basic client application.
ServiceName.bas An example file that illustrates how to use the service class
in a spreadsheet. This module is dependent on objects in
the project template that Developer provides. It is not
intended for use “as is” in custom applications.
ServiceName.cls The service object. You include this object into your own
project.
Note: You cannot use Developer to generate browser‐based clients.
Assumptions
webMethods Integration Server is running.
The input values for the services you want to invoke are determined. You will need to
include the input values in the URL that you use to invoke a service.
Limitations
When you test a service using the Run in Browser command, only input values of the type
String and String list will be passed to the service. Input values of the type document,
document list, Object, and Object list will not be displayed when the Web page is served.
1 2 3 4 5
http://IS_server:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1
Item Description
1 Identifies the webMethods Integration Server on which the service you want
to invoke resides.
2 Specifies the required keyword “invoke”, which tells webMethods
Integration Server that the URL identifies a service that is to be invoked.
3 Identifies the folder in which the service to invoke resides. Separate
subfolders with periods. This field is case sensitive. Be sure to use the same
combination of upper and lower case letters as specified in the folder name
on webMethods Integration Server.
4 Identifies the service that you want to invoke. This field is case sensitive. Be
sure to use the same combination of upper and lower case letters as specified
in the service name on webMethods Integration Server.
5 Specifies the input values for the service. Specify a question mark (?) before
the input values. The question mark signals the beginning of input values.
Each input value is represented as variable=value. The variable portion is case
sensitive. Be sure to use the same combination of upper and lower case letters
as specified in your service. If your service requires more than one input
value, separate each variable=value with an ampersand (&).
Note: Only specify this part of the URL when using the HTTP GET method.
Note: If you are serving the Web pages that invoke services from a webMethods
Integration Server, you can use a relative URL to invoke the service. By doing so, you
can serve the exact Web page from several servers without having to update the
URLs.
Specify the URL for the service in the ACTION attribute and “POST” in the METHOD attribute.
For example:
<FORM ACTION="/invoke/sample.webPageDemo/getProductCost" METHOD="POST">
After the user fills in the form and submits it, the Web browser creates a document that
contains the information the user supplied in the HTML form (performs an HTTP POST).
The browser invokes the URL identified in the ACTION attribute, which invokes the
service on webMethods Integration Server, and the browser posts the document that
contains the user’s input information to webMethods Integration Server. For more
information about how the server creates the IData object that it sends to the service, see
“Input to the Service” on page 343.
Note: Avoid using input variable names that end in “List.” Although the Integration
Server will accept variable names ending in “List,” the resulting IData may not be
structured in the way you need. For example, if you were to pass in a variable called
“skuList,” the resulting IData will contain a String called “skuList” and a String list
called “skuListList.” Moreover, if you were to pass in variables named “sku” and
“skuList,” subsequent “sku” and “skuList” variables in the query string may not be
placed in the IData fields as expected.
If you must use “List” at the end of your variable name, consider using “list”
(lowercase) or appending one or more characters at the end of the name (for example,
abcListXX).
When the server receives multiple input values that are associated with the same variable
name, the String variable in the IData object contains only the value of the first variable;
the String list variable contains all values. For example, the following shows a URL that
contains two values for the variable year and the resulting IData object that the server
creates:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999
Similarly, if the HTML form contains two fields with the same name and a user supplies
values for more than one, the String variable in the IData object contains only the value of
the first variable; the String list variable contains all values. For example, the following
shows sample HTML code that renders check boxes:
<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>
If the browser user selects all check boxes, the document that is posted to webMethods
Integration Server will contain three values for the variable named Color. The following
shows the IData object that the server passes to the service:
The following sections contain more information about each of these tasks.
Note: You can also use built‐in services to add, modify, and delete event subscriptions.
These services are located in the pub.event folder. For more information about built‐in
services, see the webMethods Integration Server Built‐In Services Reference.
Subscribing to an Event
You can use the Event Manager in Developer to subscribe to an event on the current
server. This action registers the event handler with the Event Manager and specifies
which events will invoke it. To access the Event Manager, use the ToolsEvent Manager
command.
Use the following procedure to subscribe to an event on the current server. To perform
this procedure, you must have already:
Identified the event type you want to subscribe to
Identified the service or services that generate an event you want to subscribe to (if
you want to subscribe to an audit event, exception event, or GD Start event)
Written the event handler that will execute when the identified event occurs
1 On the Tools menu, click Event Manager.
2 In the Event Manager dialog box, in the View event subscribers for list, select the event
type to which you want to subscribe.
3 Click to add a new subscriber.
4 In the Enter Input Values dialog box, complete the following fields:
Service The fully qualified name of the event handler that will subscribe to the
event (that is, the service that will execute when the event occurs). You
can either type the name in the Service field or click to locate and
select the service from a list.
Example: sgxorders.Authorization:LogAuthTrans
Filter A pattern string to further limit the events this event handler subscribes
to. Filters vary depending on the event type you are subscribing to.
For example, if you are subscribing to an audit or exception event,
create a filter to specify the names of services whose events this event
handler subscribes to (that is, the services that, when executed, will
invoke the event handler specified in Service).
You can use the * character as a wildcard (this is the only wildcard
character recognized by this pattern string). The pattern string is case
sensitive.
For more information about creating event filters, see “Creating Event
Filters” on page 352.
Comment An optional descriptive comment about this subscription.
Enabled Whether the subscription is active or inactive. Set to true to activate the
subscription. Set to false to deactivate the subscription. (This allows you
to temporarily suspend a subscription without deleting it.)
5 Click OK. Subscriptions take effect immediately.
Note: Integration Server saves information for event types and event subscriptions in
the eventcfg.bin file. This file is generated the first time you start the Integration
Server and is located in the following directory: IntegrationServer_directory\config.
Copy this file from one Integration Server to another to duplicate event subscriptions
across servers.
The following table identifies the information that you can filter on for each event type.
Notice that you cannot create a filter for some event types. For these event types, every
generated event invokes the event handlers subscribed to it.
Important! The asterisk (*) is the only wildcard character allowed in an event filter. All
other characters in the pattern string are treated as literals. Pattern strings are case
sensitive.
sgxorders.Auth:creditAuth The service sgxorders.Auth:creditAuth.
sgxorders.Auth:credit* All services in the sgxorders.Auth folder, starting with the
characters “credit.”
sgxorders.Auth:* All services in the sgxorders.Auth folder.
sgxorders.* All services in the sgxorders folder and its subfolders.
*.Auth*:credit* All services starting with the characters “credit” that
reside in any subfolder whose name starts the
characters “Auth.”
*:credit* All services starting with the characters “credit” in any
folder.
* All services.
1 On the Tools menu, click Event Manager.
2 In the View event subscribers for list, select the event type for which you want to view
subscriptions.
3 Click the subscription you want to edit, and then click .
4 Modify the fields in the Enter Input Values dialog box as needed and then click OK.
5 Repeat steps 2–4 for each subscription you want to view or edit.
6 Click OK when you finish viewing or editing event subscriptions. Your changes take
effect immediately.
1 On the Tools menu, click Event Manager.
2 In the Event Manager dialog box, in the View event subscribers for list, select the event
type for which you want to suspend a subscription.
3 Click the subscription you want to edit, and then click .
4 In the Enter Input Values dialog box, in the Enabled list, select false.
5 Repeat steps 2–4 for each event subscription you want to suspend.
6 Click OK when you finish suspending event subscriptions. Your changes take effect
immediately.
1 On the Tools menu, click Event Manager.
2 In the Event Manager dialog box, in the View event subscribers for list, select the event
type for which you want to delete a subscription.
3 Click the subscription you want to delete, and then click .
4 Repeat steps 2 and 3 for each subscription you want to delete.
5 Click OK when you finish deleting events. Your changes take effect immediately.
Create an empty flow service and name it processLogon.
1 On the editor toolbar, click and select Browse.
2 In the Browse dialog box, navigate to and select the pub.client:smtp service. Click OK.
to The email address for the person to send event notification to.
subject %userid% logged in
The subject of the email message will contain the user ID of the
person who logged on to the Integration Server as a member of the
Administrators group.
mailhost The network name of your mailhost (for example,
mail@mycompany.com).
body Administrators user %userid% logged into session %sessionName%
with session ID %ssnid%
The body of the email message will contain the user name, session
name, and session ID for the person who logged on to the
Integration Server as an Administrator.
4 On the File menu, click Save to save the service.
Use the testing and debugging tools in Developer (such as TestRun) to test and
debug the service. For more information about these tools, see Chapter 11, “Testing
and Debugging Services”.
3 Click to add a new event subscription.
4 In the Enter Input Values dialog box, complete the following fields:
5 Click OK. Subscriptions take effect immediately.
Key Description
time A String containing the date and time that the alarm event occurred, in the
format yyyy/MM/dd HH:mm:ss.SS
service A String containing the fully qualified name of the service that generated
the event. A service can generate an alarm event when a client invokes a
service that accesses information or a service on a remote server. If the
client is not a member of an allowed group for the port on the remote
server, the service will generate an alarm event.
sessionID A String containing the identification number for the session during which
the alarm event was generated. Some alarm events are not generated
during sessions. In these cases, the sessionID variable will not contain a
value.
msg A String containing the error message from the alarm event.
Tip! When you subscribe an event handler to an alarm event, you can create a filter for
the msg field to be more selective about the alarm events that invoke the event
handler.
Key Description
time A String containing the date and time the event occurred. By default, the
format is yyyy‐MM‐dd HH:mm:ss z. You can set the format by specifying
the watt.server.dateStampFmt property. For instructions about how to
specify server property settings, see the webMethods Integration Server
Administrator’s Guide.
threadID A String containing the hash identifying the server thread that generated the
audit event.
service A String containing the fully qualified name of the service that generated
the event.
ssnid A String containing the identification number for the session of the service
that generated the event.
result A String indicating the audit point. Will be one of the following:
String Description
Started This event marks the beginning of a service.
Ended This event marks the end of a service that executed
successfully.
Failed This event marks the end of a service that executed
unsuccessfully (that is, threw an exception) and is not
configured to retry or has exhausted all retries.
Note: To capture details about any exception that is thrown
when a service fails, you must subscribe to Exception Events.
For information about Exception Events, see the following
section.
Retried A retried event will be created each time a service is retried.
Events are only created for a service if auditing for that type of
event is enabled for the service (for example, start events will
not be created unless auditing for service start is enabled for
that service).
Key Description
pipeline A copy of the state of the pipeline at the point where the event occurred.
Note that this element is only included in the input object if the Include
pipeline property is set to Always or On errors only or if the watt.server.auditLog
server property is set to verbose. For more information about the Include
pipeline property in the Audit category of the Properties panel, see “Including
the Pipeline in the Audit Log” on page 143.
user A String containing the user name that invoked the service that generated
the event.
The audit event handlers that you build can make use of these inputs as they need to.
Keep in mind that when the service’s Log on option is set to Error, success, and start an audit
event handler is called twice each time a service runs: once when the service starts and
again when it ends. Your event handler can check the value of the result parameter to
determine whether it is processing an audit event from before or after the service
executed. For more information about the Log on property in the Audit category of the
Properties panel, see “Specifying When Audit Data Is Generated” on page 142.
Also, if your event handler needs data from the invoking service’s pipeline, make sure
that service’s Include pipeline option is set to Always or On errors only. Otherwise, the pipeline
element won’t be included in the input object that is passed to your event handler.
Tip! When you subscribe an event handler to an audit event, you can create a filter for
the service field to specify the services whose audit events you want to subscribe to.
That is, you can specify which services’ audit events invoke the event handler.
Note: Keep in mind that event handlers are processed independently of the services
that invoke them. They are completely separate, asynchronous processes. Event
handlers are not designed to replace the error handling and/or error recovery
procedures that you would normally include in your service.
If a nested service throws an exception, an exception event is generated by each service in
the call stack. For example, if service A1 calls service B1, and B1 throws an exception,
both B1 and A1 generate exception events (in that order).
Key Description
time A String containing the date and time the event occurred. By default,
the format is yyyy‐MM‐dd HH:mm:ss z. You can set the format by
specifying the watt.server.dateStampFmt property. For instructions
about how to specify server property settings, see the webMethods
Integration Server Administrator’s Guide.
error A String containing the error message from the exception.
localizedError A String containing the error message text in the language that
corresponds to your locale.
errorType A String containing the exception type that was thrown.
errorDump A String containing more detailed information about the exception (if
the exception object contains dump information).
service A String containing the fully qualified name of the service that
generated the event.
user A String containing the user that requested the service that generated
this event.
callStack A document (IData object) containing the items in the call stack. See the
pub.event:callStackItem IS document type for the definition of the
documents in callStack.
pipeline A copy of the state of the pipeline at the point when the exception
occurred.
threadID A String identifying the thread that invoked the service.
ssnid A String containing the identification number of the session during
which the exception occurred.
errorMsgID A String containing the identification number for the error message.
errorDetails A document (IData object) containing additional exception information
provided by the author of the Java service. For more information about
constructing exceptions to return additional information, see the
webMethods Integration Server Java API Reference for the
com.wm.util.LocalizedException class.
nestedErrorInfo A document (IData object) containing any nested errors and
exceptions. See the pub.event:exceptionInfo IS document type for the
definition of the items in nestedErrorInfo.
Tip! When you subscribe an event handler to an exception event, you can create a filter
for the service field to specify the services whose exception events you want to
subscribe to. That is, you can specify which services’ exception events invoke the
event handler.
A Guaranteed Delivery Transaction generates Guaranteed Delivery Events and Transaction Events
1 2
Service A Service B
5 4 3
Stage Description
1 Service A uses guaranteed delivery to invoke Service B on the remote
Integration Server. When the local server requests Service B, the local server
generates a GD Start event. By default, the GD Start event is logged to the
txoutyyyymmdd.log file.
2 The remote Integration Server receives the request and begins executing
Service B. When the remote server begins executing Service B, the remote
server generates a Tx Start event. By default, the Tx Start event is logged to
the txinyyyymmdd.log file.
3 The remote Integration Server finishes executing Service B and generates a Tx
End event. By default, the Tx End event is logged to the txinyyyymmdd.log
file.
4 The remote Integration Server sends the results of Service B to the requesting
client (here, the local Integration Server).
5 The local Integration Server receives the results of Service B and generates a
GD End event. By default, the GD End event is logged to the
txoutyyyymmdd.log file.
For details about guaranteed delivery, see the Guaranteed Delivery Developer’s Guide.
Key Description
time A String containing the date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
TID A String containing the transaction identification number of the service
that generated the GD Start event.
Key Description
svcname A String containing the name of the service invoked using guaranteed
delivery.
result A String containing the status of the guaranteed delivery transaction, such
as NEW.
Tip! When you subscribe an event handler to a GD Start event, you can create a filter
for the svcname field to specify the services in a guaranteed delivery transaction that
you want to subscribe to. That is, you can specify the services that when invoked
using guaranteed delivery will invoke the event handler.
Key Description
time A String containing the date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
TID A String containing the transaction identification number of the service that
generated the GD End event.
result A String containing the status of the guaranteed delivery transaction, such as
DONE.
Key Description
portStatusInfo A document reference list containing status information for each
configured port on the Integration Server.
String Description
time A String containing the date and time that the event
occurred, in the format yyyy/MM/dd HH:mm:ss.SS.
port A String containing the number for the port.
status A String indicating the status of the port.
protocol A String indicating the type of port (for example, http,
https, ftp, or e‐mail).
primary A String indicating the primary port. By default, the
Integration Server designates an HTTP port at port 5555 as
the primary port.
enabled A String indicating whether or not the port is enabled. The
value will be one of the following:
String Description
true The port is enabled.
false The port is disabled.
Key Description
time A String containing the date and time that the event occurred, in the
format yyyy/MM/dd HH:mm:ss.SS.
action A user‐defined String describing the action (such as create or push) for
the replication event. You can use the value of the action variable to
maintain separate logs for each action type.
package A String containing the name of the released or pushed package.
service A String containing the name of the flow service that invoked the
pub.replicator:generateReplicationEvent service.
Tip! When you subscribe an event handler to a replication event, you can create a filter
to specify the package that, when replicated, will invoke the event handler.
Key Description
time A String containing the date and time the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
sessionID A String containing the identification number of the session.
userid A String containing the user ID that the IS client or developer used to
log on to the Integration Server.
sessionName A String containing the name of the new session.
Tip! When you subscribe an event handler to a Session Start event, you can create a
filter so that only session start events generated by a specific user or by a member of a
specific group invoke the event handler.
Key Description
time A String containing the date and time that the event occurred, in the
format yyyy/MM/dd HH:mm:ss.SS.
sessionID A String containing the identification number of the session.
rpcs A String containing the number of service calls performed during the
session.
age A String identifying how long the session existed (in milliseconds)
before it ended.
Key Description
time A String containing the date and time the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
sessionID A String containing the identification number of the session.
rpcs A String containing the number of service calls performed during the
session.
age A String identifying how long the session existed (in milliseconds)
before it expired.
Note: The Integration Server provides an agent that you can configure for use with a
network monitoring system. For information about implementing this agent, see the
readme file in the agentInstall.jar file located in the IntegrationServer_directory\lib
directory.
Key Description
startTime A String containing the date and time that the event occurred, in the
format yyyy/MM/dd HH:mm:ss.SS.
uptime A String identifying the length of time the server has been running, in
the format yyyy/MM/dd HH:mm:ss.SS.
Key Description
totalMem A String identifying the total amount of used and unused storage
space available (in kilobytes) to the Integration Server.
freeMem A String identifying the amount of unused storage space available (in
kilobytes) to the Integration Server.
usedMem A String identifying the amount of storage used (in kilobytes) by the
Integration Server.
freeMemPer A String identifying the percentage of free memory.
usedMemPer A String identifying the percentage of used memory.
svrT A String identifying the number of executing services.
svrTMax A String identifying the maximum number of services that executed
concurrently during the previous poll cycle.
sysT A String identifying the number of threads in use.
sysTMax A String identifying the maximum number of threads that executed
concurrently during the previous poll cycle.
conn A String identifying the number of current sessions on the Integration
Server.
connMax A String identifying the maximum number of connections that ran
concurrently during the previous poll cycle.
reqTotal A String identifying the total number of requests during the poll cycle.
reqAvg A String identifying the average processing duration for a service
during the previous poll cycle.
newReqPM A String identifying the new requests per minute at the beginning of
the poll cycle.
endReqPM A String identifying the new requests per minute at the end of the poll
cycle.
errSvc A String identifying the number of services that completed with errors
since the Integration Server started.
svcRate A String identifying the number of service starts and ends per second
during the last poll cycle.
ssnUsed Number of licensed sessions currently active.
ssnPeak Greatest number of licensed sessions that have run concurrently on the
server.
ssnMax Maximum number of sessions for which the server is licensed.
errSys A String identifying the number of errors that were not caused by
services in the previous poll cycle.
Key Description
time A String containing the date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
TID A String containing the transaction ID for the guaranteed delivery
transaction that generated the event.
result A String containing the status of the guaranteed delivery transaction, such
as NEW.
Key Description
time A String containing the date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS.
TID A String containing the transaction ID of the guaranteed delivery
transaction that generated the event.
result A String containing the status of the guaranteed delivery transaction, such
as DONE.
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Requirements for Retrying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Building a Service that Throws an Exception for Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Overview
When creating a service, you can construct and configure the service to retry
automatically if a transient error occurs during service execution. A transient error is an
error that arises from a temporary condition that might be resolved or restored, such as
the unavailability of a resource due to network issues or failure to connect to a database.
The service might execute successfully if the Integration Server waits a short interval of
time and then retries the service.
To signal the Integration Server to re‐execute the service, you can build the service to
throw an ISRuntimeException when a transient error occurs. Then, if a service ends
because of an ISRuntimeException and you set retry properties for the service (or the
trigger calling the service), Integration Server will re‐execute the service using the
original service input.
This appendix provides guidance for building flow services that retry if a transient error
occurs during service execution.
Note: If you invoke an adapter service within a flow service that uses the try‐catch
structure, and the try contains an adapter service, make sure that the catch structure
can interpret the adapter service exception that signals a retry. You must ensure that
the error evaluating logic in the catch structure can account for the adapter service
exception that signals a retry. If it does not, the Integration Server will not retry the
flow service. For details about building a flow service that throws an
ISRuntimeException, see “Building a Service that Throws an Exception for Retry”,
below.
For more information about adapter services, see the relevant adapter guides.
Note: This section describes one possible way to build a service that throws an
exception for retry.
Important! The pub.flow:getLastError service must be the first service invoked within
the catch sequence. If it is not the first service invoked, and a preceding service in
the catch sequence fails, the error thrown in the try sequence will be overwritten
with the new error.
Note: If the flow service includes an adapter service, and a transient error
occurs during adapter service execution, the adapter service throws an
exception that extends the ISRuntimeException.
If the service can be retried, set a flag to indicate this. For example, you might set a
variable named isTransientError to “true”. A subsequent BRANCH step will use
the flag to determine whether to execute the pub.flow:throwExceptionForRetryService.
Keep in mind that you might need to use more than one service to handle the error,
determine if it was caused by a transient error, and set the transient error flag.
Make sure to insert the exception evaluation logic within the catch sequence, but after
the pub.flow:getLastError service.
7 Insert a BRANCH step that branches on the value of the transient error flag. This BRANCH
step will determine if an ISRuntimeException should be thrown. You can branch on a
switch value or branch on an expression. Do one of the following:
If you are branching on a switch value, in the Switch property, specify the name of
the pipeline variable whose value will act as the switch. For example, if you use
the isTransientError variable as the flag to indicate that a transient error occurred,
you would use isTransientError as the switch.
If you are branching on an expression, set the Evaluate labels property to True.
.
Important! You must position the BRANCH step so that it is outside of the try and
catch sequences and is a sibling of the outer sequence. This is because exceptions
thrown within a sequence are ignored and the BRANCH step will contain the
pub.flow:throwExceptionForRetry service.
Name Description
wrappedException An Object containing any exception that you want to include
as part of this ISRuntimeException. This might be the
exception that causes the pub.flow:throwExceptionForRetry service
to execute. For example, if the service attempts to connect to a
database and the connection attempt fails, you might map the
exception generated by the database connection failure to the
wrappedException parameter.
message A string containing a message to be logged as part of this
exception.
Note: If you want to insert retry logic into a service that makes database calls or
involves transactions, your service needs to include logic for starting, committing,
and rolling back the transaction. Specifically, the rollback call should be made in the
catch sequence.
# Description
# Description
Step Description
# Description
BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
BRANCH
The BRANCH step selects and executes a child step based on the value of one or more
variables in the pipeline. You indicate the variables you want to branch on by specifying a
switch value or by writing an expression that includes the variables.
Name1
if the value of choice is
Name2
if the value of choice is
Name of the
switch field is NameN
choice if the value of choice is
$null
if choice does not exist or has
a value of ‘$null’
no
if the value of choice is an
empty string “ “
$defaul
Otherwise
Branching on Expressions
When you branch on expressions, you set the Evaluate labels property of the BRANCH
step to true. In the Label property for each child step, you write an expression that
includes one or more variables. At run time, the BRANCH step executes the first child
step with an expression that evaluates to true.
If you want to specify a child step to execute when none of the expressions are true, set
the label of the child step to $default.
Child2
if the expression of second child is true
Evaluate
labels is set to
true ChildN
if the expression of nth child is
$defau
Otherwise
The BRANCH step in the following illustration evaluates expressions to determine which
child steps execute. The run‐time value of BuyerAccount, PromotionalCode, or
shippingMethod determines the shipping charges added to an order.
Properties
The BRANCH step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for the step.
Scope Optional. Specifies the name of a document (IData object) in the
pipeline to which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step
should run. If this time elapses before the step completes, the server
waits for the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Property Description
Label Optional. (Required if you are using this BRANCH step as a target for
another BRANCH or EXIT step.) Specifies a name for this instance of
the BRANCH step, or a null, unmatched, or empty string ($null,
$default, blank).
Switch Specifies the String field that the BRANCH step uses to determine
which child flow step to execute. The BRANCH step executes the child
flow step whose label matches the value of the field specified in the
Switch property. Do not specify a value if you set the Evaluate labels
property to True.
Evaluate Specifies whether or not you want the server to evaluate labels of child
labels steps as conditional expressions. When you branch on expressions, you
enter expressions in the Label property for the children of the BRANCH
step. At run time, the server executes the first child step whose label
evaluates to True. To branch on expressions, select True. To branch on the
Switch value, select False.
EXIT
The EXIT step exits the entire flow service or a single flow step. Specifically, it may exit
from the nearest ancestor loop step, a specified ancestor step, the parent step, or the
entire flow service.
The EXIT step can throw an exception if the exit is considered a failure. When an
exception is thrown, user‐specified error message text is displayed by typing it directly or
by assigning it to a variable in the pipeline.
Properties
The EXIT step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for the step.
Label Optional. (Required if you are using this EXIT step as a target for a
BRANCH step.) Specifies a name for this specific step, or a null,
unmatched, or empty string ($null, $default, blank).
Exit from Required. Specifies the flow step or service from which you want to
exit.
Specify this value… To exit the…
$parent Parent flow step, regardless of the type of step.
$loop Nearest parent LOOP or REPEAT step.
$flow Entire flow.
label Nearest ancestor step that has a label that
matches this value.
Note: If the label you specify does not match the
label of an ancestor flow step, the flow will exit
with an exception.
Signal Required. Specifies whether the exit is considered a success or a
failure. A SUCCESS condition exits the flow service or step. A FAILURE
condition exits the flow service or step and throws an exception. The
text of the exception message is contained in the Failure message
property.
Failure Optional. Specifies the text of the exception message that is displayed
message when Signal is set to FAILURE. If you want to use the value of a pipeline
variable for this property, type the variable name between % symbols.
For example, %mymessage%.
INVOKE
The INVOKE flow step invokes another service. You can use it to invoke any type of
service, including another flow service.
Properties
The INVOKE step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for the step.
Scope Optional. Specifies the name of a document (IData object) in the
pipeline to which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step
should run. If this time elapses before the step completes, the server
waits for the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property,
type the variable name between % symbols. For example,
%expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Label Optional. (Required if you are using this step as a target for a
BRANCH or EXIT step.) Specifies a name for this specific step, or a
null, unmatched, or empty string ($null, $default, blank).
Service Required. Specifies the fully qualified name of the service to invoke.
Validate input Optional. Specifies whether the server validates the input to the
service against the service input signature. If you want the input to be
validated, select True. If you do not want the input to be validated,
select False.
Validate output Optional. Specifies whether the server validates the output of the
service against the service output signature. If you want the output to
be validated, select True. If you do not want the output to be validated,
select False.
LOOP
The LOOP step takes as input an array variable that is in the pipeline. It loops over the
members of an input array, executing its child steps each time through the loop. For
example, if you have a service that takes a string as input and a string list in the pipeline,
use the LOOP step to invoke the service one time for each string in the string list.
You identify a single array variable to use as input when you set the properties for the
LOOP step. You can also designate a single variable for output. The LOOP step collects
an output value each time it runs through the loop and creates an output array that
contains the collected output values. If you want to collect more than one variable,
specify a document that contains the fields you want to collect for the output variable.
more input
array
input is
members?
an array
Yes
get next
member of child child child
input array
Properties
The LOOP step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for the step.
Scope Optional. Specifies the name of a document (IData object) in the
pipeline to which you want to restrict this step. If you want this step to
have access to the entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step
should run. If this time elapses before the step completes, the server
waits for the step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Property Description
Label Optional. (Required if you are using this step as a target for a BRANCH
or EXIT step.) Specifies a name for this specific step, or a null,
unmatched, or empty string ($null, $default, blank).
Input array Required. Specifies the input array over which to loop. You must
specify a variable in the pipeline that is an array data type (that is,
String list, String table, document list, or Object list).
Output array Optional. Specifies the name of the field in which the server places
output data for an iteration of the loop. The server collects the output
from the iterations into an array field with the same name. You do not
need to specify this property if the loop does not produce output values.
MAP
The MAP step adjusts the pipeline at any point in a flow. It makes pipeline modifications
that are independent of an INVOKE step.
Within the MAP step, you can:
Link (copy) the value of a pipeline input field to a new or existing pipeline output
field.
Drop an existing pipeline input field. (Keep in mind that once you drop a field from
the pipeline, it is no longer available to subsequent services in the flow.)
Assign a value to a pipeline output field.
Perform document‐to‐document mapping in a single view by inserting transformers.
Properties
The MAP step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for this step.
Scope Optional. Specifies the name of a document (IData) in the pipeline to which
you want to restrict this step. If you want this step to have access to the
entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, the server waits for the
step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Label Optional. (Required if you are using this step as a target for a BRANCH or
EXIT step.) Specifies a name for this specific step, or a null, unmatched, or
empty string ($null, $default, blank).
REPEAT
The REPEAT step repeatedly executes its child steps up to a maximum number of times
that you specify. It determines whether to re‐execute the child steps based on a Repeat on
condition. You can set the repeat condition to one of the following:
Repeat if any one of the child steps fails.
Repeat if all of the elements succeed.
You can also specify a time period that you want the REPEAT flow step to wait before it
re‐executes its child steps.
reps = reps + 1
Exit
Properties
The REPEAT step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for this step.
Scope Optional. Specifies the name of a document (IData object) in the pipeline
to which you want to restrict this step. If you want this step to have access
to the entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, the server waits for the
step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Label Optional. (Required if you are using this step as a target for a BRANCH or
EXIT step.) Specifies a name for this specific step, or a null, unmatched, or
empty string ($null, $default, blank).
Count Required. Specifies the maximum number of times the server re‐executes
the child steps in the REPEAT step. Set Count to 0 (zero) to instruct the
server that the child steps should not be re‐executed. Set Count to a value
greater than zero to instruct the server to re‐execute the child steps up to a
specified number of times. Set Count to -1 to instruct the server to re‐
execute the child steps as long as the specified Repeat on condition is true.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %servicecount%.
Property Description
Repeat Optional. Specifies the number of seconds the server waits before re‐
interval executing the child steps. Specify 0 (zero) to re‐execute the child steps
without a delay.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %waittime%.
Repeat on Required. Specifies when the server re‐executes the REPEAT child steps.
Select SUCCESS to re‐execute the child steps when the all the child steps
complete successfully. Select FAILURE to re‐execute the child steps when
any one of the child steps fails.
SUCCESS A child within the REPEAT block fails.
FAILURE The Count limit is reached before its children execute
successfully.
If the REPEAT step is a child of another step, the failure is propagated to its parent.
SEQUENCE
The SEQUENCE step forms a collection of child steps that execute sequentially. This is
useful when you want to group a set of steps as a target for a BRANCH step.
You can set an exit condition that indicates whether the sequence should exit prematurely
and, if so, under what condition. Specify one of the following exit conditions:
Exit the sequence when a child step fails. Use this condition when you want to ensure that
all child steps are completed successfully. If any child step fails, the sequence ends
prematurely and the sequence fails.
Exit the sequence when a child step succeeds. Use this condition when you want to define
a set of alternative services, so that if one fails, another is attempted. If a child step
succeeds, the sequence ends prematurely and the sequence succeeds.
Exit the sequence after executing all child steps. Use this condition when you want to
execute all of the child steps regardless of their outcome. The sequence does not end
prematurely.
Properties
The SEQUENCE step has the following properties.
Property Description
Comments Optional. Specifies a descriptive comment for this step.
Scope Optional. Specifies the name of a document (IData object) in the pipeline to
which you want to restrict this step. If you want this step to have access to
the entire pipeline, leave this property blank.
Timeout Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, the server waits for the
step to complete and then raises an exception.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%.
If you do not need to specify a time‐out period, leave Timeout blank.
Label Optional. (Required if you are using this step as a target for a BRANCH or
EXIT step.) Specifies a name for this specific step, or a null, unmatched, or
empty string ($null, $default, blank).
Property Description
Exit on Required. Specifies when to exit the SEQUENCE step.
Specify this value... To...
FAILURE Exit the sequence when a child step fails. (Execution
continues with the next flow step in the flow service.)
The SEQUENCE step executes its child steps until either
one fails or until it executes all its child steps. This is the
default.
Note: When a SEQUENCE step exits on failure, the
Integration Server rolls back the pipeline contents. That
is, the Integration Server returns the pipeline to the state
it was in before the SEQUENCE step executed.
SUCCESS Exit the sequence when a child step executes
successfully or after all child steps fail. (Execution
continues with the next flow step in the flow service.)
DONE Exit the sequence after all child steps execute.
The SEQUENCE step executes all of its child steps
regardless of whether they succeed or fail.
Important! Characters in regular expressions are case sensitive.
retains the first 30 characters in each matching element and discards the rest.
Use this
symbol… To…
. Match any single character except a new line.
Example doc.p[/web.ethods/].text
This example would return any paragraph containing the string ‘web’
followed by any single character and the string ‘ethods’. It would match
both ‘webMethods’ and ‘webmethods’.
Use this
symbol… To…
^ Match the beginning of the string or line.
Example doc.p[/^webMethods/].text
This example would return any paragraph containing the string
‘webMethods’ at the beginning of the element or at the beginning of any
line within that element.
$ Match the end of the string or line.
Example doc.p[/webMethods$/].text
This example would return any paragraph containing the string
‘webMethods’ at the end of the paragraph element or at the end of any
line within that element.
* Match the preceding item zero or more times.
Example doc.p[/part *555-A/].text
This example would return any paragraph containing the string ‘part’
followed by zero or more spaces and then the characters ‘555‐A’.
+ Match the preceding item 1 or more times.
Example doc.p[/part +555-A/].text
This example would return any paragraph containing the string ‘part’
followed by one or more spaces and then the characters ‘555‐A’.
? Match the preceding item 0 or 1 times.
Example doc.p[/part ?555-A/].text
This example would return any paragraph containing the string ‘part’
followed by zero or one space and then the characters ‘555‐A’.
( ) When used in an index, these characters group an item within the regular
expression.
Example doc.p[/part(,0)+May/].text
This example would return any paragraph containing the string ‘part’
followed by one or more occurrences of the characters ‘,0’ and then the
characters ‘May”.
When used in a mask, they specify characters that you want to retain.
Example doc.p[].text[(^.{25}).*]
This example would keep the first 25 characters within each paragraph
and discard the rest.
Use this
symbol… To…
{n } Match the preceding item exactly n times.
Example doc.p[/^.{24}webmethods/].text
This example would return any paragraph in which the word
‘webmethods’ started in the 25th character position of the paragraph.
{n ,} Match the preceding item n or more times.
Example doc.p[/^.{10,}webmethods/].text
This example would return any paragraph in which the word
‘webmethods’ appeared anywhere after the 10th character position of the
paragraph. That is, this example would return a paragraph in which the
word ‘webmethods’ started in the 11th or later character position of the
paragraph.
{0,m } Match the preceding item none or at most m times.
Example doc.p[/^.{0,4}webmethods/].text
This example would return any paragraph in which the word
‘webmethods’ started in any of the first 5 character positions of the
paragraph.
{n ,m } Match the preceding item at least n times, but not more than m times.
Example doc.p[/^.{1,4}webmethods/].text
This example would return any paragraph in which the word
‘webmethods’ started in character position 2 through 5 of the paragraph.
| Match the expression that precedes or follows this character.
Example doc.p[/webmethods|webMethods/].text
This example would return any paragraph that contained either
‘webmethods’ or ‘webMethods’.
\b Match a word boundary.
Example doc.p[/\bport\b/].text
This example would return any paragraph that contained the word ‘port’,
but not paragraphs that contained these characters as part of a larger
word, such as ‘import’, ‘support’, ‘ports’ or ‘ported’.
\B Match a boundary that is not a word boundary.
Example doc.p[/\B555-A/].text
This example would return any paragraph that contained the characters
‘555‐A’ as part of a larger word such as AZ555‐A, or Dept555‐A, but not
‘555‐A’ alone.
Use this
symbol… To…
\A Match only at the beginning of a string (equivalent to ^).
Example doc.p[/\AwebMethods/].text
This example would return any paragraph containing the string
‘webMethods’ at the beginning of the element or at the beginning of any
line within that element.
\Z Match only at the end of a string (or before a new line at the end).
Example doc.p[/webMethods\Z/].text
This example would return any paragraph containing the string
‘webMethods’ at the end of the paragraph element or at the end of any
line within that element.
\n Match a new line.
Example doc.p[/webMethods\n/].text
This example would return any paragraph containing the string
‘webMethods’ followed by the new line character.
\r Match a carriage return.
Example doc.p[/webMethods\r/].text
This example would return any paragraph containing the string
‘webMethods’ followed by a carriage return.
\t Match a tab character.
Example doc.p[/\twebMethods/].text
This example would return any paragraph containing the string
‘webMethods’ preceded by a tab character.
\f Match a form feed character.
Example doc.p[/webMethods\f/].text
This example would return any paragraph containing the string
‘webMethods’ followed by a form feed character.
\d Match any digit. Same as [0‐9].
Example doc.p[/part \d555-A/].text
This example would return any paragraph containing a part number that
starts with any digit 0 through 9, and is followed by the characters 555‐A.
Therefore, it would match ‘part 1555‐A’ but not ‘part A555‐A’ or ‘part
#555‐A’.
Use this
symbol… To…
\D Match any non‐digit. Same as [^0‐9].
Example doc.p[/part \D555-A/].text
This example would return any paragraph containing a part number that
starts with any character other than 0 through 9, and is followed by the
characters 555‐A. Therefore, it would match ‘part A555‐A’ and ‘part #555‐
A’, but not ‘part 1555‐A’.
\w Match any word character. Same as [0‐9a‐z_A‐Z].
Example doc.p[/part \w4555-A/].text
This example would return any paragraph containing a part number that
starts with a letter or digit and is followed by the characters 555‐A.
Therefore, it would match ‘part A555‐A’ and ‘part 1555‐A’, but not ‘part
#555‐A’.
\W Match any nonword character. Same as [^0‐9a‐z_A‐Z].
Example doc.p[/part \W4555-A/].text
This example would return any paragraph containing a part number that
starts with a character other than a letter or digit, and is followed by the
characters 555‐A. Therefore, it would match ‘part #555‐A’ and ‘part ‐555‐
A’, but not ‘part 1555‐A’ or ‘part A555‐A’.
\s Match any white‐space character. Same as [\t\n\r\f].
Example doc.p[/\swebMethods/].text
This example would return any paragraph containing the string
‘webMethods’ if it is preceded by a tab character, a new line character, a
carriage return, or a form‐feed character.
\S Match any nonwhite‐space character. Same as [^\t\n\r\f].
Example doc.p[/\SwebMethods/].text
This example would return any paragraph containing the string
‘webMethods’, if that string is not preceded by a tab character, a new line
character, a carriage return, or a form‐feed character.
\0 Match a null string.
Example doc.p[/[^\0]/].text
This example would return any paragraph that is not empty (null).
\xnn Match any character with the hexadecimal value nn.
Example doc.p[/\x1FwebMethods/].text
This example would return any paragraph containing the ASCII unit‐
separator character (1F) followed by the characters ‘webMethods’.
Use this
symbol… To…
[ ] Match any character within the brackets.
Example doc.p[/part [023]555-A/].text
This example would return any paragraph containing a part number that
starts with the numbers 0, 2, or 3 and is followed by the characters 555‐A.
Therefore, it would match ‘part 0555‐A’ and ‘part 2555‐A’, but not ‘part
4555‐A’.
The following characters have special meaning when used within
brackets:
Use this char… To…
^ Exclude characters from the pattern.
Example doc.p[/part [^023]555-A/].text
This example would return any paragraph containing a
part number that does not start with the numbers 0, 2,
or 3, but is followed by the characters 555‐A. Therefore,
it would match ‘part 4555‐A’ and ‘part A555‐A’, but not
‘part 0555‐A’.
- Specify a range of allowed characters.
Example doc.p[/part [A-M]555-A/].text
This example would return any paragraph containing a
part number that starts with any letter A through M and
is followed by the characters 555‐A. Therefore, it would
match ‘part A555‐A’ and ‘part J555‐A’, but not ‘part
N555‐A’.
Data Types
Data is passed in and out of a service through an IData object. An IData object is the
collection of name/value pairs on which a service operates. An IData object can contain
any number of elements of any valid Java objects, including additional IData objects and
IDataCodable objects.
Each element stored in an IData object corresponds to a data type. The following table
identifies the data types supported by Developer.
Note: You can view the actual data types represented by Object or Object list icons in
built‐in services by looking up the service in the webMethods Integration Server Built‐In
Services Reference.
Note: Developer displays small symbols next to a variable icon to indicate validation
constraints. Developer uses to indicate an optional variable. Developer uses the ‡
symbol to denote a variable with a content constraint. For information about applying
constraints to variables, see “Applying Constraints to Variables” on page 255.
Note: When you input values for a constrained Object during testing or when
assigning a value in the pipeline, Developer validates the data to make sure it is of the
correct type.
The following table identifies the Java classes you can apply to Objects and Object list
variables in Developer.
Note: Object and Object list variables constrained with a Java classes should be linked
only to other Object and Object list variables of the same Java class or of unknown
type. Although Developer permits a link between constrained Objects of different
Java classes, the run‐time behavior is undefined. For more information about
specifying Java classes for Objects, see “Considerations for Object Constraints” on
page 257.
value X value
Y value
Z value
X [empty] X
Y
Z
X [empty] X
Y Y
Z Z
X A X
Y B Y
Z C Z
No link occurs.
V A
W B
X C
Y
Z
Note: A source variable that is the child of a document list is treated like an array
because there is one value of the source variable for each document in the document
list. For example:
DocumentLis StringList
String
Where the value of DocumentList1 is... Then the value of StringList1 is…
DocumentLis StringList
a
DocumentList1 b
c
String
a
DocumentList1
String b
DocumentList1
String c
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Rules for Use of Expression Syntax with the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Overview
webMethods Integration Server provides syntax and operators that you can use to create
expressions for use with the BRANCH step, pipeline mapping, and triggers.
In a BRANCH step, you can use an expression to determine the child step that
webMethods Integration Server executes. At run time, the Integration Server executes
the first child step whose conditional expression evaluates to “true”. For more
information about the BRANCH step, see “The BRANCH Step” on page 160
In pipeline mapping, you can place a condition on the link between variables. At run
time, webMethods Integration Server only executes the link if the assigned condition
evaluates to “true.” For more information about applying conditions to links between
variables, see “Applying Conditions to Links Between Variables” on page 204.
For Broker/local triggers, you can further refine a subscription by creating filters for
the publishable document types. A filter specifies criteria for the contents of a
document. At run time, the Broker or Integration Server applies the filter to the
document. The Broker or Integration Server will route or process the document only
if the document meets the filter criteria. For more information, see the Publish‐
Subscribe Developer’s Guide.
Important! If multiple conditions in the trigger specify the same publishable
document type, the filter applied to the publishable document type must be the
same in each condition.
For JMS triggers, you can create local filters to further limit the messages a JMS
trigger processes. A filter specifies criteria for the contents of the message body.
Integration Server applies a local filter to the message after the JMS trigger receives
the message from the JMS provider. If the message meets the filter criteria, Integration
Server executes the trigger service specified in the routing rule.
When you write expressions and filters, keep the following points in mind:
Operators, variable names, and strings are case sensitive.
White space between the tokens of an expression is ignored.
Some syntax that is valid on the Integration Server is not valid on the Broker. If the
syntax is valid for a Broker, the Integration Server saves the filter with the
subscription on the Broker. If the syntax is not valid, the Integration Server saves the
subscription without the filter on the Broker. Subscriptions and filters are always
saved on the Integration Server.
For a list and an example of syntax that prevents a filter from being saved on the
Broker, see “Rules for Use of Expression Syntax with the Broker” on page 428.
Syntax
When you create an expression, you need to determine which values to include in the
expression. Values can be represented as variable names, regular expressions, numbers,
and strings. The following table identifies the types of values you can use in an
expression and the syntax for each value type.
price Value of the price
variable
%address/postalCode% Value of the postalCode
variable in the address
document
%poItems[0]% Value of the first
element in the poItems
array
Note: Strings not enclosed in quotes (ʹ or ʺ) are
interpreted as variable names.
If the object is
constrained as type... Use this syntax...
Boolean ʺtrueʺ or ʺfalseʺ
Example: %myBoolean%=="true"
The string constant in the expression is case insensitive. For
example, the expressions %myBoolean%=="true" and
%myBoolean%=="tRUe" are equivalent.
Byte ʺxxʺ
Example: ʺ10ʺ (for 0X0A)
Character ʺaʺ
Example: ʺCʺ
Double xxxxxx.x or xxxxxx or ‐xxxxxx
Example: 123456.0, 123456, ‐123456
Float xxxx.x or ‐xxxx.x
Example: 1234.1, ‐1234.1
Integer xxxxx or ‐xxxxx
Example: 12345, ‐12345
Long xxxxxx or ‐xxxxxx
Example: 123456 or ‐123456
Short xxx or ‐xxx
Example: 123 or ‐123
Date ʺyyyy‐MM‐dd HH:mm:ss timezoneʺ
Example: ʺ2002‐06‐25 00:00:00 EDTʺ
customerID The customerID variable exists and
is not null.
Variable !variableName Evaluates to true if the specified variable does not
does not exist or is null.
exist
This example... Evaluates to true if...
!quantity The quantity variable does not
exist or is null.
!color & !size The color variable does not exist or
is null and the size variable does
not exist or is null.
Operators
Expressions can include relational and logical operators. Relational operators are used to
compare values to each other. Logical operators are used to combine multiple expressions
into a single condition.
Relational Operators
You can use relational operators to compare the value of two fields or you can compare
the value of a field with a constant. The Integration Server provides two types of
relational operators: standard and lexical.
Standard relational operators can be used in expressions and filters to compare the
contents of fields (variables) with other variables or constants.
Lexical relational operators can be used to compare the contents of fields (variables)
with string values in Broker/local trigger filters.
Relational operators are sometimes called comparison operators.
Note: You can also use standard relational operators to compare string values.
However, filters that use standard relational operators to compare string values will
not be saved with the trigger subscription on the Broker. If the subscription filter
resides only on the Integration Server, the Broker automatically places the document
in the subscriber’s queue. The Broker does not evaluate the filter for the document.
The Broker routes all of documents to the subscriber, creating greater network traffic
between the Broker and the Integration Server and requiring more processing by the
Integration Server.
= a = b Equal to.
This example... Evaluates to true if...
!= a != b Not equal to.
This example... Evaluates to true if..
quantity != 0 The value of the quantity variable
does not equal 0 (zero).
<> a <> b Not equal to.
This example... Evaluates to true if..
Note: To set the filter collation locale, use the Broker user interface to select the
Broker Server for which you want to change the locale. On the Broker Server
Information screen, select Change Broker Server Filter Collation Locale. Then, on the
Change Filter Collation Locale screen, in the New Locale list, select the locale you
want to use. Restart the Broker Server for the change to take effect.
If you use a lexical operator to compare strings in an expression (such as in a
BRANCH step or in a pipeline link), the Integration Server treats the lexical operators
as if they were standard relational operators.
If you use a lexical operator to compare a value that is not a string with another string
value, the Integration Server treats the non‐string value as an empty string (that is, ʺʺ).
For example, in the expression (%myInt% L_EQUALS ""), the %myInt% variable is
declared to be of type integer. This expression always evaluates to true because
%myInt% contains an integer value that the Integration Server treats as an empty string
(ʺʺ) when it evaluates the expression.
Filters that use lexical relational operators to compare string values will be saved with
the trigger subscription on the Broker. Filters that use standard relational operators to
compare string values will not be saved on the Broker.
When you view filters on the Broker user interface, a lexical operator appears as its
equivalent standard operator. For example, the expression %myString% L_EQUALS
"abc" appears as myString=="abc".
The following table describes the lexical operators that you can use in filters.
Operator Description
L_EQUALS Lexical equal to.
This example... Evaluates to true if..
Logical Operators
You can use the following logical operators in expressions to create conditions consisting
of more than one expression:
! ! expr Negates the next expression.
This example... Evaluates to true if..
Precedence
webMethods Integration Server evaluates expressions in a condition according to the
precedence level of the operators in the expressions.
The following table identifies the precedence level of each operator you can use in an
expression.
1 ( )
2 not, !
3 =, ==, !=, <>, >, >=, <, <=
4 and, &, &&
5 or, |, ||
Note: To override the order in which expressions in a condition are evaluated, enclose
the operations you want evaluated first in parentheses. webMethods Integration
Server evaluates expressions contained in parentheses first.
Addressing Variables
In an expression, you can refer to the values of variables that are children of other
variables and refer to the values of elements in an array variable. To address children of
variables or an element in an array, you need to use a directory‐like notation to describe
the position of the value.
variableName Address a variable.
Example: state
Variable state.
variableName/childVariableName Address the child variable of a
variable (such as a field in a
document).
Example: %buyerInfo/state%
Variable state within IS document type
buyerInfo.
arrayVariableName[index] Address an element in an array.
Example: orderItems[0]
Value of the first element in the
orderItems array.
arrayVariableName[rowIndex][columnIndex] Address an element in a
two‐dimensional array (String table).
Example: dictionary[1][2]
Value of the element located in the
third column of the second row in the
dictionary array.
duplicateVariableName(index) Address an occurrence of a variable
where there are multiple variables
with the same name in the document
or pipeline. The index is zero‐based.
Example: address(1)
Value of the second variable named
address.
%ʺvariableWithSpecialCharactersʺ% Address a variable whose name
contains special characters. Variables
that contain special characters must
be enclosed in quotation marks.
Example: %ʺaddress(work)ʺ%
Value of the variable named
address(work).
For more information, see
“Addressing Variables that Contain
Special Characters” below.
Notes:
To view the path to a variable in the pipeline, rest the mouse pointer over the variable
name. Developer displays the variable path in a tool tip.
To copy the path to a variable in a pipeline, select the variable, right‐click, and select
Copy.
You can enclose variable names in %, for example %buyerInfo/state%. If the variable
name includes special characters, you must enclose the path to the variable in %
(percent) symbols and enclose the variable name in ʺ ʺ (quotation marks). For more
information about using variables as values in expressions, see “Syntax” on page 415.
Following are some examples of how to address variables that contain special characters.
Type... To...
%ʺDate/Timeʺ% Address a variable named Date/Time.
%purchaseOrder/"Date/Timeʺ% Address a variable named Date/Time in the
document variable purchaseOrder.
Note: If you did not enclose Date/Time in
quotation marks, and instead had
%purchaseOrder/Date/Time% or
%ʺpurchaseOrder/Date/Timeʺ%, the expression
would address a variable named Time in a
document named Date that was contained in a
document named purchaseOrder.
%ʺaddress(work)ʺ/ʺphone(cell)ʺ% Address a variable named phone(cell) in the
document variable address(work).
%ʺDate\\Timeʺ% Address a variable named Date\Time.
\ backslash \\
[ opening bracket
] closing bracket
( opening parenthesis
) closing parenthesis
% percent \%
" quotation marks \ʺ
/ slash mark (forward)
Important! When you use variable names with special characters in expressions or
filters, you must enclose the variable name in ʺ ʺ (quotation marks).
Note: Broker saves as much of a filter as possible with the subscription. For example,
suppose that a filter consists of more than one expression, and only one of the
expressions contains syntax Broker considers invalid. Broker saves the expressions it
considers valid but does not save the expression containing invalid syntax.
(Integration Server saves all the expressions.)
Keep the following points in mind when writing filters for Broker/local triggers:
Expressions that specify field names that contain syntax, characters, symbols, or
words the Broker considers restricted or reserved will not be saved on the Broker.
All expressions must contain a relational (comparison) operator.
Use lexical relational operators (such as L_EQUALS, L_LESS_THAN) to compare fields of
type String.
Use standard relational operators (such as =, ==, !=, <, >, <= and >=) to compare fields
that are not of type String.
Use the =, ==, <>, or != operators to compare a value with an Object constrained as a
Boolean.
The following table identifies syntax that the Broker considers invalid. Expressions with
this syntax will be saved on the Integration Server but not on the Broker.
Tip! You can use the Broker user interface to view the filters (expressions) saved with a
subscription. If the expression does not appear with the subscription on the Broker,
then the expression contains invalid syntax.
No comparison operators "fieldName"
"!fieldName"
jcode Template
The following code provides a template describing the tags (highlighted) that the jcode
utility uses to identify code segments in a Java source file.
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>> ---
jcode Example
The following is a complete example of properly commented Java source code.
Sample Code—IData
The following is an example of a class whose services (methods) take IData objects as
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.
*/
/**
* == 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
// [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");
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Overview
You can apply content constraints to variables in the IS document types, specifications, or
service signatures that you want to use as blueprints in data validation. Content
constraints describe the data a variable can contain. At validation time, if the variable
value does not conform to the content constraints applied to the variable, the validation
engine considers the value to be invalid. For more information about validation, see
Chapter 10, “Performing Data Validation”.
When applying content constraints to variables, you can do the following:
Select a content type. A content type specifies the type of data for the variable value,
such as string, integer, boolean, or date. A content type corresponds to a simple type
definition in a schema.
Set constraining facets. Constraining facets restrict the content type, which in turn,
restrict the value of the variable to which the content type is applied. Each content
type has a set of constraining facets. For example, you can set a length restriction for a
string content type, or a maximum value restriction for an integer content type.
For example, for a String variable named itemQuantity, you might specify a content type
that requires the variable value to be an integer. You could then set constraining facets
that limit the content of itemQuantity to a value between 1 and 100.
The content types and constraining facets described in this appendix correspond to the
built‐in data types and constraining facets in XML Schema. The World Wide Web
Consortium (W3C) defines the built‐in data types and constraining facets in the
specification XML Schema Part 2: Datatypes (http://www.w3c.org/TR/xmlschema‐2).
Content Types
The following table identifies the content types you can apply to String, String list, or
String table variables. Each of these content types corresponds to a built‐in simple type
defined in the specification XML Schema Part 2: Datatypes.
Note: The anyURI type indicates that the variable value plays the
role of a URI and is defined like a URI. webMethods Integration
Server does not validate URI references because it is impractical
for applications to check the validity of a URI reference.
base64Binary Base64‐encoded binary data.
Constraining Facets
enumeration, length, maxLength, minLength, pattern
boolean True or false.
Constraining Facets
pattern
Example
true, 1, false, 0
byte A whole number whose value is greater than or equal to –128 but
less than or equal to 127.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
-128, -26, 0, 15, 125
date A calendar date from the Gregorian calendar. Values need to
match the following pattern:
CCYY‐MM‐DD
Where CC represents the century, YY the year, MM the month, DD
the day. The pattern can include a Z at the end to indicate
Coordinated Universal Time or to indicate the difference between
the time zone and coordinated universal time.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
1997-08-09 (August 9, 1997)
double Double‐precision 64‐bit floating point type.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
6.02E23, 3.14, -26, 1.25e-2
gMonth A Gregorian month that occurs every year. Values must match the
following pattern:
‐‐MM
Where MM represents the month. The pattern can include a Z at
the end to indicate Coordinated Universal Time or to indicate the
difference between the time zone and coordinated universal time.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
--11 represents November
gMonthDay A specific day and month that recurs every year in the Gregorian
calendar. Values must match the following pattern:
‐‐MM‐DD
Where MM represents the month and DD represents the day. The
pattern can include a Z at the end to indicate Coordinated
Universal Time or to indicate the difference between the time zone
and coordinated universal time.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
--09-24 represents September 24th
gYearMonth A specific month and year in the Gregorian calendar. Values must
match the following pattern:
CCYY‐MM
Where CC represents the century, YY the year, and MM the
month. The pattern can include a Z at the end to indicate
Coordinated Universal Time or to indicate the difference between
the time zone and coordinated universal time.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
2001-04 indicates April 2001
hexBinary Hex‐encoded binary data.
Constraining Facets
enumeration, length, maxLength, minLength, pattern
ID A name that uniquely identifies an individual element in an
instance document. The value for ID needs to be a valid XML
name. The ID datatype represents the ID attribute type from the
XML 1.0 Recommendation.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
IDREF A reference to an element with a unique ID. The value of IDREF is
the same as the ID value. The IDREF datatype represents the
IDREF attribute type from the XML 1.0 Recommendation.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
integer A positive or negative whole number.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
-2500, -5, 0, 15, 365
language Language identifiers used to indicate the language in which the
content is written. Natural language identifiers are defined in
IETF RFC 1766.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
long A whole number with a value greater than or equal to
–9223372036854775808 but less than or equal to
9223372036854775807.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example -55600, -23, 0, 256, 3211569432
Name XML names that match the Name production of XML 1.0 (Second
Edition).
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
NCName Non‐colonized XML names. Set of all strings that match the
NCName production of Namespaces in XML.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
NMTOKEN Any mixture of name characters. Represents the NMTOKEN
attribute type from the XML 1.0 Recommendation.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
NMTOKENS Sequences of NMTOKENS. Represents the NMTOKENS attribute
type from the XML 1.0 Recommendation.
Constraining Facets
enumeration, length, maxLength, minLength
nonNegativeInteger An integer with a value greater than or equal to 0.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
0, 15, 32123
nonPositiveInteger An integer with a value less than or equal to 0.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits, whiteSpace
Example
-256453, -357, -1, 0
normalizedString Represents white space normalized strings. Set of strings
(sequence of UCS characters) that do not contain the carriage
return (#xD), line feed (#xA), or tab (#x9) characters.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
Example
MAB-0907
short A whole number with a value greater than or equal to ‐32768 but
less than or equal to 32767.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
-32000, -543, 0, 456, 3265
string Character strings in XML. A sequence of UCS characters (ISO
10646 and Unicode). By default, all white space is preserved for
variables with a string content constraint.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
Example
MAB-0907
time An instant of time that occurs every day. Values must match the
following pattern:
hh:mm:ss.sss
Where hh indicates the hour, mm the minutes, and ss the seconds.
The pattern can include a Z at the end to indicate Coordinated
Universal Time or to indicate the difference between the time zone
and coordinated universal time.
Constraining Facets
enumeration, maxExclusive, maxInclusive, minExclusive,
minInclusive, pattern
Example
18:10:00-05:00 (6:10 pm, Eastern Standard Time) Eastern
Standard Time is 5 hours behind Coordinated Universal Time.
token Represents tokenized strings. Set of strings that do not contain the
carriage return (#xD), line feed (#xA), or tab (#x9) characters,
leading or trailing spaces (#x20), or sequences of two or more
spaces.
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
unsignedInt A whole number greater than or equal to 0, but less than or equal
to 4294967295.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
0, 22335, 123223333
unsignedLong A whole number greater than or equal to 0, but less than or equal
to 18446744073709551615.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
0, 2001, 3363124
unsignedShort A whole number greater then or equal to 0, but less than or equal
to 65535.
Constraining Facets
enumeration, fractionDigits, maxExclusive, maxInclusive,
minExclusive, minInclusive, pattern, totalDigits
Example
0, 1000, 65000
Constraining Facets
When you apply a content type to a variable, you can also set constraining facets for the
content type. Constraining facets are properties that further define the content type. For
example, you can set a minimum value or precision value for a decimal content type.
Each content type has a set of constraining facets. The constraining facets described in the
following table correspond to constraining facets defined in the specification XML Schema
Part 2: Datatypes.
whiteSpace The white space normalization
performed on the variable value.
The value of whiteSpace can be one
of the following:
preserve: No white space
normalization is performed.
replace: Carriage returns (#xD),
line feeds (#xA), and tabs (#x9) are
replaced with a single space
(#x20).
collapse: After the white space
normalization specified by replace
is performed, sequences of spaces
(#x20) and leading and trailing
spaces (#x20) are removed.
Note: Previous versions of XML Schema contained the constraining facets duration,
encoding, period, precision, and scale. However, these constraining facets are not
included in the recommendation of XML Schema Part 2: Datatypes. The constraining
facets duration, encoding, and period were removed. precision was renamed totalDigits.
scale was renamed fractionDigits. If you view a content type from an IS schema created
from an XML Schema Definition that used pre‐Recommendation version of XML
Schema (before May 2001) the Content Type dialog box will display the constraining
facets that were available in the pre‐Recommendation version of XML Schema.
Note: The word “fixed” appears next to the name of a constraining facet whose value
is fixed and cannot be changed. When a facet has a fixed value, the facet is called a
fixed facet.
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
IS Schema Generation Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Overview
This appendix describes error messages that can occur during data validation, IS schema
generation, or IS document type generation.
When the validation engine in the webMethods Integration Server validates an object (an
XML node, the pipeline, or documents) and the object does not conform to the blueprint
or model, the server generates errors and/or exceptions. You might also receive errors
and exceptions when creating an IS schema. The following sections describe the errors
and exceptions you can receive when performing validation and when creating an IS
schema.
Validation Errors
When you perform validation using a built‐in service, webMethods Integration Server
returns validation errors in the errors output variable if the object is invalid. When you
perform input/output validation, webMethods Integration Server throws an exception if
the inputs or outputs are invalid. Error messages are contained in the exception.
Each validation error contains a code and a default message. Error code prefixes indicate
the validation error type:
DT indicates a data type validation error. Data type validation errors pertain to the
content type constraints applied to the variables.
NV indicates a node validation error. Node validation errors pertain to the validation
of an XML node.
VV indicates a document validation error. Document validation errors pertain to the
structure of the data values (for example, an invalid document structure).
The following table describes the validation errors you can receive when performing
XML, pipeline, or document validation.
However, the schema processor is unable to resolve the
QName using the namespace declarations in the instance
document.
Response: Check to make sure that the document
conforms to the schema.
NV‐014 [ISC.0082.9017] typeName is not validly derived from
declaredTypeName
Cause: This error occurs when the first type is used in a
context where the second type is expected, and either the
first type is not the same as the second type or the first
type is not validly derived from the second type.
Response: Check to make sure that the correct types are
specified in the schema and that the correct
corresponding types are used in the document.
Validation Exceptions
At run time, the service performing validation either succeeds or fails. If the service fails,
webMethods Integration Server throws a validation exception. A validation exception is
generated if one of the following is true:
Errors are detected in the object (XML node, pipeline, or document (IData object))
that is passed (for example, null value).
The basic validation contract is violated (for example, a binary tree is passed instead
of a document (IData object) as expected).
You specify that the service should fail if the object to be validated (XML node,
pipeline, or document (IData object)) did not conform to the IS schema or IS
document type (for example, failIfInvalid = true). If this is the reason for the exception,
webMethods Integration Server inserts the validation errors into the exception
message.
The following table identifies and describes the validation exceptions that can be
generated.
Note: You might also receive these errors and warnings when you generate an IS
document type or flow service from an XML Schema definition, DTD, or XML
document that references a DTD. For more information about creating an IS
document type, see “Creating an IS Document Type” on page 233. For more
information about creating a flow service, see “Creating a New Flow Service” on
page 120.
Symbols adding
! 423 folders 121
!= 420 packages 72
" 427 transformers 214
% 427 variables to pipeline link 211
& 424 addressing
&& 424 variables in expressions and filters 425
( 427 variables with special characters 426
) 427 alarm events
/ 427 building handlers for 360
< 420 definition of 348, 359
<= 421 reasons generated 359
<> 420 uses of 359
= 419 all content model 227
== 419 Allow unspecified fields option 256
> 420 and operator 424
>= 420 annotating source code for jcode 320
\ 427 anonymous type definitions 227
_env field 243 any attribute declaration 226
| 423 any element declaration 226
|| 423 anyURI content constraint 439
‡ 259 API for Java services 314
applying
A conditions to links 204
constraints to variables 255, 438
access control 104
areas of Developer window
ACLs
behavior and operation 31
assigning to elements 104, 107
editor 27
assigning to packages and folders 106
focus 31
checking for services 105
general layout 21
defined 104
Navigation panel 22
element creation, view, and deletion implications
Properties panel 29
112
Recent Elements tab 27
inheritance 109
resizing 33
locking implications 111
Results panel 31
requirements for using Developer 18
switching perspectives 34
testing and debugging implications 111
UDDI Registry tab 25
viewing on a server 109
zooming 33
actions, performing on IS elements 32
arithmetic services 214
adapter notifications
array variables
described 243
default behavior for linking 409
guidelines for moving and copying 49
definition of 409
adapter services, retry behavior 376
O identifying dependencies 81
Object data type importing into Java services 313, 319
definition of 407 moving 74
in filters 429 naming guidelines 72
Object list data type, definition of 407 pasting 74
object list variables, Java classes 407 reloading 77
object variables, Java classes 407 reloading vs refreshing 77
online help, obtaining 38 removing dependencies 83
open and closed documents 256 required by Java services 319
open documents, described 256 viewing details 73
opening a session on webMethods Integration viewing patch history 79
Server 35 panels
operations, performing on IS elements 32 editor 27
operators Navigation 22
conditional expressions and filters 418 Properties 29
lexical relational operators 421 Recent Elements 27
logical 423 Results 31
precedence in expressions 424 switching perspectives 34
relational 418 UDDI Registry 25
standard relational operators 419 parameters
optional variables for validation 256 applying constraints 255
or operator 423 benefits of declaring 122
out of sync publishable document types 244 declaring 122, 126
Output array property 179 declaring for a service 123, 124
output templates parent/child relationships in a flow 154
assigning to a service 127 passwords
definition of 127 changing 37
output variables requirements 37
declaring 124 patch history
declaring for a service 122 removal by Integration Server 80
declaring in a document (IData object) 233 viewing for a package 79
linking considerations 194 pattern constraining facet 449
linking in the pipeline 193 pattern matching, in event subscriptions 352
Overwrite Pipeline Value option 207 Perform Variable Substitution option 208
Performance 144
P performance impact, service auditing 144
permission
packages
See also ACLs
adding 72
assigning to elements 104
assigning version numbers 78
Permissions property 107
copying 74
perspectives of views 34
creating 72
pipeline
creating circular dependencies 83
adding variables to 211
cutting 74
addressing variables 425
definition of 70
adjusting 190
deleting 77
assigning values to 206
dependencies, using with startup services 84
changing values 295
documenting 76
checking for variables 418
exporting 78
R replication services 86
Recent Elements tab shutdown services 86
described 25, 27 startup services 86
help about 38 variables from the pipeline 210
hiding and showing 33 renaming
resizing 33 IS elements 51
Record data type. See document data type transformers 221
Record list data type. See document list data type Repeat on property 170, 171, 393
Record Reference data type. See document REPEAT step
reference data type creating (on failure) 172
Record Reference List data type. See document creating (on success) 174
reference list data type definition of 118, 391
records. See document (IData object), IS document failure 171
types specifying the repeat condition 170, 171, 393
recursive complex types in XML Schemas 238 using in a flow 170
redefine mechanism, in XML Schemas 230 using to retry a failed step 171
re-enabling using to retry a successful step 174
flow steps 291 replace white space 449
transformers 293 replication events
referenced elements, importing during building handlers for 368
synchronization 241 definition of 349, 367
references uses of 367
finding 61 replication services
inspecting pipeline 63 assigning 85
refresh definition of 84
difference from restoring a session 36 guidelines for assigning 85
Navigation panel contents 25 removing 86
Recent Elements tab contents 27 when to use 84
regular expressions requirements for passwords 37
creating event filters with 355 requiring variable existence for validation 256
definition of 398 Reset command 283
operators 398 resizing
using as a BRANCH label 161 panels 33
using in a mask 398 window areas 33
reinvoking services 146 Restore Pipeline from Server command 299
relational operators Restore Pipeline Locally command 299
definition of 418 restorePipelineFromFile service 296, 298
lexical 421 restoring
standard 419 pipeline values from a file
types of 418 into Results panel 299
reloading packages 77 overview 298
remote servers, invoking services on 158 with restorePipelineFromFile service 299
remote services, invoking 158 sessions 36
removing Results panel
breakpoints 291 copying elements from 277
breakpoints from transformers 290 described 31
package dependencies 83 general information 276
packages 77 help about 38
W X
warnings XML documents
document (IData object) generation 470 creating documents (IData objects) from 233
flow service generation 470 creating IS document types from 235
IS schema generation 470 creating IS schemas from 229
watt.server.auditLog property, described 148 testing services with 280
watt.server.invoke.maxRetryPeriod 136 XML Namespace property, described 247
watt.server.stats.pollTime property 366 XML Schema definitions
webMethods Developer creating documents (IData objects) from 233
main window 21 creating IS document types from 235
online help 38 creating IS schemas from 229
starting 19 import mechanism 230
toolbar 26 include mechanism 230
webMethods Integration Server IS schema generation warnings 470
access requirements for 18 recursive complex types 238
closing a session 35 redefine mechanism 230
connecting to 19, 35 referenced by other XML Schemas 230
disconnecting from 35 XML validation
logging on to 19 content constraints 224
notification of shutdown 36 creating IS schemas 229
opening a session 35 definition of 264
performing ACL checking 105 errors 452
supported data types 406 exceptions 465
webMethods Monitor 140, 146 IS schemas, overview 224
webMethods Type Library 333, 337, 339 performing 264
When to include input pipeline options, described structural constraints 224
143
When to log options, described 142 Z
whiteSpace constraining facet 449 zooming
win32.COM.dispatch:createObject 328 in a window 33
windows in on transformers 220
layout 21
zooming 33
WmPublic package, definition of 158