Professional Documents
Culture Documents
8-2-SP2 Developer Users Guide
8-2-SP2 Developer Users Guide
8-2-SP2 Developer Users Guide
October 2011
Copyright
& Document ID
This document applies to webMethods Developer Version 8.0 and webMethods Integration Server Version 8.2 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright 19982011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or
their licensors.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
http://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AGs licensing conditions and terms. These terms are part of the product
documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products." This document is part of the product documentation, located at
http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
Table of Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deprecation of webMethods Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
17
17
18
18
21
22
22
23
25
26
26
29
29
30
31
31
33
35
35
35
36
37
37
37
38
39
40
41
41
41
42
45
46
47
47
48
48
49
Table of Contents
49
50
51
53
53
53
54
55
57
59
59
62
62
64
65
66
66
67
69
72
72
75
76
76
78
78
79
79
81
82
83
84
84
85
86
88
90
90
90
91
91
91
92
93
Table of Contents
Publishing and Retracting Information about Integration Server and Trading Networks Assets
93
Publishing Metadata about Integration Server and Trading Networks Assets . . . . . . . 94
Retracting Published Metadata about Integration Server and Trading Networks Assets 95
Usage Notes for Publishing/Retracting IS Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Checking the Status of Publication and Retraction Requests . . . . . . . . . . . . . . . . . . . 98
Status Information for Publication and Retraction Requests . . . . . . . . . . . . . . . . . 98
4. Locking and Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Is a Lock? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Do I Know Who Has an Element Locked? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When Do I Lock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When Do I Unlock an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking Java and C/C++ Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing the Status of Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copying, Moving, or Deleting Locked Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unlocking Elements Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unlocking an Element Using the Integration Server Administrator . . . . . . . . . . . . . . . .
Unlocking a System Locked Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing an Elements Corresponding Server Files . . . . . . . . . . . . . . . . . . . . . . . .
Automatically Unlocking Elements After Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Lock/Unlock Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Package Management Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Save Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101
102
102
103
103
103
104
104
105
106
106
107
108
108
109
110
111
112
113
113
113
114
115
115
116
117
118
118
119
120
120
121
122
123
123
124
Table of Contents
125
125
125
126
126
129
130
130
131
132
133
134
135
135
135
136
137
137
138
139
140
142
145
145
146
147
147
147
147
148
148
149
151
152
153
153
154
155
155
156
157
159
161
161
Table of Contents
163
163
165
165
166
167
167
167
168
169
171
172
173
174
175
176
177
177
178
178
178
180
180
181
181
183
184
185
186
188
190
190
191
191
191
194
196
196
198
199
200
200
202
205
Table of Contents
207
208
208
209
211
212
212
213
213
217
220
220
221
221
222
224
225
225
226
227
228
228
229
229
230
231
232
233
233
235
235
237
238
238
239
239
239
240
241
242
243
243
Table of Contents
277
278
278
279
281
282
283
284
285
286
287
288
288
289
291
291
Table of Contents
10
293
294
294
295
296
298
298
299
301
301
302
303
304
305
305
306
307
307
308
309
310
311
312
313
313
314
315
316
316
317
318
319
321
321
322
322
323
323
324
325
325
326
326
Table of Contents
327
327
328
328
329
331
332
332
332
333
333
334
334
335
335
335
337
338
339
341
341
341
342
343
343
343
344
345
346
346
347
347
347
348
349
350
352
352
352
353
354
11
Table of Contents
12
356
356
357
357
358
358
358
359
359
360
360
360
360
361
361
361
362
362
362
363
363
363
363
364
365
365
365
366
366
367
367
369
370
370
371
372
372
372
373
373
374
375
375
376
Table of Contents
Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Submitting and Receiving XML via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting and Receiving XML via HTTP without Parsing . . . . . . . . . . . . . . . . . . . . . .
Example: Submitting and Receiving XML via HTTP without Parsing . . . . . . . . . . . . . .
Submitting and Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FTPing a File from a webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving XML via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting and Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Sending XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving XML via E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
377
377
378
378
379
380
380
381
382
382
382
383
385
386
388
388
389
389
391
394
394
395
395
396
396
398
399
399
399
400
400
400
401
402
403
403
403
404
405
405
13
Table of Contents
14
409
409
410
412
415
416
416
417
418
419
419
419
420
420
420
421
422
422
423
424
424
425
425
426
427
427
428
428
430
B. Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a Regular Expression in a Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Regular Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
431
432
432
433
439
440
441
443
444
D. Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparing Java Objects to Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
447
448
449
451
Table of Contents
452
453
453
453
455
457
459
460
461
462
463
E. jcode tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample CodeIData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
465
466
467
467
471
472
473
483
487
488
488
502
507
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
15
Table of Contents
16
Document Conventions
Convention
Description
Bold
Narrow font
UPPERCASE
Italic
Identifies variables for which you must supply values specific to your
own situation or environment. Identifies new terms the first time they
occur in the text.
Monospace
font
{}
Indicates a set of choices from which you must choose one. Type only
the information inside the curly braces. Do not type the { } symbols.
17
Convention
Description
[]
Indicates one or more options. Type only the information inside the
square brackets. Do not type the [ ] symbols.
...
Indicates that you can type multiple options of the same type. Type
only the information. Do not type the ellipsis (...).
Documentation Installation
You can download the product documentation using the Software AG Installer.
Depending on the release of the webMethods product suite, the location of the
downloaded documentation will be as shown in the table below.
For webMethods...
6.x
7.x
8.x
Online Information
You can find additional information about Software AG products at the locations listed
below.
Note: The Empower Product Support Web site and the Software AG Documentation
Web site replace Software AG ServLine24 and webMethods Advantage.
If you want to...
Go to...
18
http://documentation.softwareag.com
Go to...
http://communities.softwareag.com/
webmethods
19
20
What Is Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22
22
Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
25
35
39
41
42
21
What Is Developer?
Note: webMethods Developer is deprecated and does not support all the features of
webMethods Integration Server 8.2. Software AG recommends the use of
webMethods Designer for service development.
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 Storing Services in a Version Control System in
the Software AG_directory\_documentation directory.
22
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
Specify...
Server type
The registered type for the server on which you want to open a
session. The default type is Integration Server.
Server
23
In this field...
Specify...
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.
Uses secure
connection
Uses proxy
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 components text in Japanese.
24
The Properties
Panel displays
the properties
for an item.
The Results
Panel displays
the results of a
services
execution.
25
Represents...
A server. You can have multiple server contexts displayed in Developer.
The active server context is the one that is highlighted in the Navigation
panel. To display the contents of the server, click the symbol next to its
name.
A package. A package contains a set of services and related files, such as
specifications, IS document types, and output templates. To display the
contents of a package, click next to its name.
A folder. A folder contains related services and optional folders (called
subfolders). To display the contents of a folder, click next to its name.
A flow service. A flow service is a service written in the webMethods flow
language.
A Web service descriptor (WSD). A Web service descriptor is an IS namespace
element that contains the definition of an IS Web service. A WSD
describes either a provider or a consumer Web service. For more
information about using Web services and the UDDI Registry, see the Web
Services Developers Guide.
26
This icon...
Represents...
A provider Web service descriptor (WSD). A Web service descriptor that
contains the definition of a provider IS Web service. A provider Web
service allows an external user to invoke an existing IS service as an
operation of the Web service.
A consumer Web service descriptor (WSD). A Web service descriptor that
contains the definition of a consumer Web service. Consumer Web
services are external Web services that can be invoked from within the
local Integration Server.
A Web service connector. A Web service connector is a flow service that
invokes a Web service located on a remote server. Developer
automatically generates a Web service connector when it creates a Web
service descriptor for a consumer Web service. Developer can also create a
Web service connector from an existing WSDL.
A Java service. A Java service is a service written in Java.
A C service. A C service is a service written in C/C++.
A specification. A specification is a formal description of a services 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 PublishSubscribe Developers 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 Using webMethods
Integration Server to Build a Client for JMS.
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.
27
This icon...
Represents...
An IS schema. An IS schema is the blueprint or model document against
which you validate an XML document. The schema defines what can and
cannot be contained in the XML documents it validates.
An adapter notification. An adapter notification enables an adapter to
receive event data from the adapters resource. There are two types of
adapter notifications:
Polling notifications, which poll the resource for events that occur on
the resource.
Listener notifications, which work with listeners to detect and process
events that occur on the adapter resource.
For information about creating an adapter notification, refer to the
documentation provided with the adapter.
An adapter service. An adapter service connects to an adapters resource
and initiates an operation on the resource. Adapter services are created
using service templates included with the adapter. For information about
creating adapter services, refer to the documentation provided with the
adapter.
A listener. A listener is an object that connects to an adapter resource and
waits for the resource to deliver data when an event occurs on the
resource. Listeners work with listener notifications to detect and process
event data on the adapter resource. For information about creating a
listener, refer to the documentation provided with the adapter.
A connection. A connection is an object that contains parameters that
adapter notifications and listeners use to connect to a resource. For
information about creating a connection, refer to the documentation
provided with the adapter.
A flat file dictionary. A flat file dictionary contains record definitions, field
definitions, and composite definitions that can be used in multiple flat file
schemas. For more information about creating a flat file dictionary, see the
Flat File Schema Developers Guide.
A flat file schema. A flat file schema is the blueprint that contains the
instructions for parsing or creating the records in a flat file, as well as the
constraints to which an inbound flat file document should conform to be
considered valid. Using flat file schemas, you can translate documents
into and from flat file formats. For more information about creating a flat
file schema, see the Flat File Schema Developers Guide.
An XSLT service. An XSLT service converts XML data into other XML
formats or into HTML, using rules defined in an associated XSLT
stylesheet. For more information about creating XSLT services, see the
XSLT Services Developers Guide.
28
This icon...
Represents...
A .NET service. A .NET service is a service that calls methods imported
from .NET assemblies (using the webMethods for Microsoft Plug-in).
Once a .NET service exists within Developer, it can become part of a flow
just like any other service. For more information about using the
Microsoft .NET application platform with webMethods components, see
the webMethods for Microsoft Package Installation and Users Guide.
An Unknown Node. The webMethods component used to create/develop the
element is not installed on the client machine.
An Unknown Service. The webMethods component used to create this
service is not installed on the client machine.
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.
29
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.
This icon...
Represents...
A UDDI Registry Node. Developer displays the URL of the UDDI Registry
to which you are connected next to the registry icon. Below the UDDI
Registry name, Developer displays all of the business entities registered
in that UDDI Registry.
A Business Entity. A business entity is a publisher of Web services to the
UDDI Registry. Below the business entity name, Developer displays the
Web services published by that entity.
A Web service. A Web service is a software application that can be
accessed remotely, using XML- based languages to communicate. From
a Web service or a WSDL, you can create a consumer Web service
descriptor and connector. Developer can invoke the connector to run
the remote Web service. From an existing IS service or WSDL, you can
create a provider Web service descriptor. You can then publish the Web
service descriptor to a UDDI Registry so that the IS service it describes
can be invoked by an external user as an operation of the Web service.
For more information about using Web services and the UDDI Registry,
see the Web Services Developers Guide.
30
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.
31
If you open
an element
from the
Navigation
panel...
...editing
controls for that
element are
displayed in the
editor.
In this example, a
specification is
opened in the
editor.
The editor lists
the input and
output fields that
were created for
this specification.
These lists are
also referred to
as trees.
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 elements title bar contains the
fully qualified name of the element and icons to indicate the elements type and lock
status. For more information about these icons, see Navigation Panel Icons on page 26
and What Is a Lock? on page 102.
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.
32
Tip! You can locate the active element in the Navigation panel by using the
EditLocate in Navigation command.
33
Properties panel
Drag to resize the Property
and Value columns.
Description of the
selected property.
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
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 elements properties are read only.
34
Click a variable
name...
For more information about service execution results, see Chapter 11, Testing and
Debugging Services.
35
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 commands 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.
36
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.
Do this...
Click
Click
Click
Click
Click
on the border between the top of the editor and
the specialized tabs beneath it.
37
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 services 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 elements detail as possible (for example, a
services pipeline).
You display a perspective as follows:
To display the...
Edit perspective
WindowEdit Perspective
Test perspective
WindowTest Perspective
Details perspective
WindowDetails Perspective
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.
38
Click to display
Edit, Test, and
Detail
perspectives.
Click to hide or
show the
Properties and
Results panels.
Drag movable
borders to
resize panels.
Complete the Open Session dialog box. For more information about completing this
dialog box, see To start Developer on page 23.
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.
39
40
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
41
Requirement
Default
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, spouses name, childs 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.
To change your password
1
In the Change Password dialog box, in the Old Password field, type your current
password.
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.
42
Press F1.
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.
43
44
What Is an Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
46
47
49
50
51
53
Renaming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
57
59
Deleting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
59
62
66
69
Caching Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
72
45
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.
Elements in the Navigation panel
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.
For information about...
See...
Locking elements
46
On the New dialog box, click the type of element you want to create and then click
Next.
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.
Click Finish.
Tip! You can quickly create an element by clicking
next to the New button on the
toolbar and then clicking the element you want to create. Developer adds the element
beneath the currently selected element, with a default name of Untitled.
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.
47
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.
48
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 Storing Services in a Version Control
System in the Software AG_directory\_documentation directory.
Tip! You can produce printable versions of many of the elements in the Navigation
panel by clicking FileView as HTML.
To...
Confirm before
deleting
49
Select...
To...
Prompt before
updating dependents
when
renaming/moving
Update local
references when
pasting multiple
elements
3
Click OK.
For more information about finding dependents, see Finding Dependents and
References on page 66.
50
The actions you can perform on items depend on the type and combination of items
you select. If an action is not allowed for one or more elements in a selection,
Developer makes the action unavailable for use. For example, Developer disables the
cut, copy, paste, and delete actions if you select a server. Developer also prevents you
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.
51
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.
52
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 elements
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.
53
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 services
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.
54
When you move or copy a publishable document type to a destination on the same
server, the moved or copied document type remains publishable. When you copy a
publishable document type to a different server, Developer converts the publishable
document type to an IS document type on the destination server. For more
information about making IS document types publishable and synchronizing them
with Broker document types, see the Publish-Subscribe Developers Guide.
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 webMethods Administering Integration Server.
Click...
EditCut
EditCopy
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.
55
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.
Select the location where you want to move or copy the elements.
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.
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
folders 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.)
56
If you clicked the Prompt before updating dependents when renaming/moving check box in
the Options dialog box and any elements on the current server contain unsaved
changes, Developer prompts you to save the element(s).
Do one of the following:
To...
Click...
Cancel
10 If you clicked Proceed without Save in Step 9, Developer identifies the elements that will
be affected by the move.
Do one of the following:
To...
Click...
Update Usages
Ignore Usages
Cancel
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.
57
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
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.
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.
If you clicked the Prompt before updating dependents when renaming/moving check box in
the Options dialog box and any elements on the current server contain unsaved
changes, Developer prompts you to save the element(s).
Do one of the following:
58
To...
Click...
Cancel
If you clicked Proceed without Save in Step 5, Developer alerts you to the elements that
will be affected by the rename action.
Do one of the following:
To...
Click...
Update Usages
Ignore Usages
Cancel
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
59
If you selected the Confirm before deleting check box in the Options dialog box, do the
following:
a
60
If any elements on the server contain unsaved changes, Developer prompts you to
save the element(s). Do one of the following:
To...
Click...
Cancel
If the elements you are deleting are not dependents of other elements, Developer
prompts you to confirm the delete action. Click OK.
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
Do this...
Click...
Continue
Cancel
61
Type...
PO
^PO
PO$
:logPO$
log..
For a complete list of regular expression operator characters, see Appendix 18, Regular
Expressions.
Note: The Find command supports regular expressions but not conditional statements.
For example, you can specify Test as a search term, but not Test OR Test1.
62
On the Edit menu, click Find. Developer displays the Find In Navigation Panel dialog
box.
In the Find In Navigation Panel box, type any portion of the fully qualified name of the
element that you want to find.
If you want to limit the scope of the search to a specific package, select the package in
the Package list.
Click Find. The Find In Navigation Panel dialog box displays the results of the search.
Results of search for PO
The term PO is
found in...
...the names of 33
elements in the
Navigation panel.
All of these
elements contain
PO in their fully
qualified name.
To jump to an element in the Navigation panel, select that element in the results and
click Go To.
Note: If you receive a Couldnt 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 elements location in the
Navigation panel using the EditLocate in Navigation command.
63
64
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.
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.
Do this...
Click Find Next. If Developer finds a match, it selects the field and displays it on the
Pipeline tab.
Click Find Next to find the next field that matches the search criteria.
In the editor, select the INVOKE step containing the service you want to locate.
On the Edit menu, click Locate in Navigation. Developer locates and selects the service in
the Navigation panel.
65
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.
To find dependents of a selected element
1
In the Navigation panel or in the editor, select the element for which you want to find
dependents.
66
...this element.
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 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.
67
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 49.
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
service A.
To find references of a selected element
1
In the Navigation panel or in the editor, select the element for which you want to find
references.
...these elements.
68
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.
This variable is a
reference to the
PODocument in the
Navigation panel.
The link between
ONum and num is a
pipeline reference.
Drop Value modifier to a field in a document reference or document reference list. The
following illustration of the Pipeline tab identifies these types of pipeline references.
Examples of pipeline references
69
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.
70
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.
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.
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.
71
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
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.
72
On the Tools menu, click Options. Developer displays the Options dialog box.
Click General.
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 servers cache, see Configuring a Services Use of
Cache on page 146.
73
74
What Is a Package? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
76
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
76
90
Publishing and Retracting Information about Integration Server and Trading Networks Assets .
93
75
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 timereporting 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 packages 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
webMethods Administering Integration Server.
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 webMethods Administering Integration Server.
To...
See...
Create a package
page 78
Activate a package
page 81
page 79
76
To...
See...
page 82
page 86 and
webMethods Administering Integration
Server
page 90
page 83 and
webMethods Administering Integration
Server
page 84 and
webMethods Administering Integration
Server
page 85 and
webMethods Administering Integration
Server
page 88
page 84
page 81 and
webMethods Administering Integration
Server
77
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 webMethods Administering Integration Server.
In the New dialog box, select Package, and then click Next.
Developer displays the New Package dialog box.
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.
78
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.
For more information about package details, see Assigning a Version Number to a
Package on page 85, Viewing the Patch History for a Package on page 86, and
Identifying Package Dependencies on page 88.
79
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
80
81
To copy a package
1
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.
Documenting a Package
You can communicate the purpose and function of a package and its services to other
developers by documenting the package.
To create documentation for a 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.
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.
82
PackageName
DocumentName
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 or Designer. 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
83
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 webMethods Administering Integration
Server.
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 66.
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
On the File menu, click Export. Developer displays the Export To dialog box.
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.
84
To export an element
1
In the Navigation panel, select the folder or element that you want to export.
On the File menu, click Export. Developer displays the Export To dialog box.
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.
In the Navigation panel, select the package to which you want to assign a version
number.
85
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).
86
Note: With the exception of the Package version field and the fields under Package
dependencies, the fields on the Settings tab are display-only.
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.
To view patch history for a package
1
In the Navigation panel, select the package for which you want to view a patch
history.
In the editor, click the packages Settings tab and review the fields under Patch history.
This field...
Specifies...
Name
Version
Build
Description
Time
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
Number
87
In the Navigation panel, select the package for which you want to specify package
dependencies.
In the Enter Input Values dialog box, enter the following information:
88
In this field...
Specify...
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
the version number.
*.* as
Click OK.
89
In the Navigation panel, select the package for which you want to remove a package
dependency.
Under Package Dependencies, select the package dependency you want to remove.
Click
90
91
Because services in a package are not made available to clients until the packages
startup services finish executing, you should avoid implementing startup services
that access busy remote servers. They will delay the availability of other services in
that package.
You can assign one or more startup services to a package; however, you cannot
specify the order in which the services execute. If you have a series of startup services
that need to execute in a specific order, create a wrapper service that invokes all the
startup services in the correct order. Designate the wrapper service as the startup
service for the package.
In the Navigation panel, select the package to which you want to assign startup,
shutdown, or replication services.
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.
Note: A service that you just created does not appear in the Available Services list if
you have not refreshed your session on the server since you created the service.
To add a shutdown service, under Shutdown services, select the service from the
Available Services list, and click
.
Repeat this step for each service you want to add as a shutdown service for the
package.
92
In the Enter Input Values dialog box, in the Service field, do one of the following:
Click
to navigate to and select the service that you want to use as a
replication service.
Click OK.
Repeat these steps for each service you want to add as a replication service.
In the Navigation panel, select the package for which you want to remove startup,
shutdown, or replication services.
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
93
Broker/local triggers
C services
Document types
Flat file dictionaries
Flat file schemas
Flow services
IS Schemas
Java services
JMS triggers
.NET services
Specifications
Web service connectors
Note: Integration Server publishes/retracts Web service connectors as part of
publishing/retracting a consumer Web service descriptor.
Web service descriptors
XSLT services
For Trading Networks, you can publish and retract information about TN document
types.
Note: Metadata about Integration Server cannot be published or retracted explicitly.
However, when you publish metadata for IS and TN assets, metadata about
Integration Server is published as well.
94
To publish metadata about an Integration Server asset, you select the package that
contains the asset whose metadata you want to publish. Developer will publish
metadata for all of the supported assets in the entire package. You cannot select
individual assets for publishing or retracting.
To publish metadata about Trading Networks assets, you select Trading Networks
Assets. Developer will publish metadata for all TN document types available on the
Integration Server to which Developer is connected.
Only one metadata operation can run at a time. If you try to submit a publication
request while a retraction or publication request is already running, you will receive
the error Operation already in progress and you will have to resubmit the request
later.
Note: This method of publishing and retracting metadata is deprecated as of
Integration Server version 8.2 SP1. Use Designer version 8.2 SP1 to publish metadata
instead.
To publish information about assets
1
To publish metadata about Integration Server assets, select one or more packages.
To publish metadata about Trading Networks assets, select Trading Networks Assets.
Click OK.
To view the status of the publication request, on the Tools menu, click Metadata >
Publish > Status.
95
publish the package (packageA) that contains serviceA. Because processA depends
on an asset in packageA, you can only retract packageA (and any of its contents) after
you retract processA. If you change processA so that it no longer references serviceA
and republish processA, you can retract packageA.
If a published IS asset is in pending state in CentraSite, retracting the package that
contains the IS asset results in an orphaned asset in CentraSite. For example, suppose
that you published a package containing an IS service to CentraSite. If you change the
life cycle state of the IS service asset to "Deploy" and then retract the package while
the state change is pending, the IS service asset is not deleted when the package is
retracted. The IS service asset becomes an orphaned asset in CentraSite.
Only one metadata operation can run at a time. If you try to submit a publication
request while a retraction or publication request is already running, you will receive
the error Operation already in progress and you will have to resubmit the request
later.
To retract information about assets
1
To retract metadata about Integration Server assets, select one or more packages.
To retract metadata about Trading Networks assets, select Trading Networks Assets.
Click OK.
To view the status of the retraction request, on the Tools menu, click Metadata >
Retract > Status.
96
To establish the correct relationships between Web service descriptors created from
WSDL documents and the CentraSite Service asset, use the New wizard in Designer
to create the Web service descriptor and select CentraSite as the source location. If you
create a Web service descriptor from a WSDL in CentraSite through the UDDI
registry or directly from a file or URL, the Uses and Implements relationships
will not be established between the Web service descriptor and the CentraSite service
asset.
If you intend to change the compatibility mode of a Web service descriptor for which
you published metadata to CentraSite, first retract metadata for the Web service
descriptor. Next, change the compatibility mode. Finally, republish metadata for the
Web service descriptor to CentraSite.
For more information about Web service descriptors and compatibility mode, see the
Web Services Developers Guide.
Each asset in CentraSite has a Deployed On property that identifies each
Integration Server from which an asset with that name has been published. However,
the Integration Servers might have published different versions of the same asset or
completely different assets that happen to have the same name. In CentraSite, it will
appear as if both Integration Servers published the exact same asset. CentraSite will
maintain the asset that was most recently published.
For example, suppose that Integration Server1 publishes a service named myService.
CentraSite creates an IS service asset with the name myService and a Deployed On
property value of Integration Server1. Later, Integration Server2 also publishes a
service named myService but the service published by Integration Server2 is not
identical to the service published by Integration Server1. CentraSite will update the IS
service asset to represent the myService service published Integration Server2.
CentraSite also updates the Deployed On property value to be: Integration Server1,
Integration Server2. CentraSite indicates that both Integration Servers published an
identical asset when, in fact, they did not.
When an Integration Server retracts an asset, CentraSite removes that Integration
Server from the Deployed On property for the CentraSite asset. If the asset is not
deployed on another Integration Server, CentraSite removes the asset. If the asset is
deployed on another Integration Server, the asset remains in CentraSite. The content
of the CentraSite asset will be the asset that was most recently published. This might
result in a CentraSite asset whose content does not represent the IS asset that was
published by the Integration Server listed in the Deployed On property.
To continue the above example in which Integration Server1 and then Integration
Server2 published different versions of services named myService, if Integration
Server2 retracts myService, CentraSite removes Integration Server2 from the
Deployed On property value. However, the content of the myService asset in
CentraSite represents the myService asset published by Integration Server2 because
Integration Server2 published the asset most recently. This results in CentraSite
indicating that the myService asset published by Integration Server2 is deployed on
Integration Server1.
97
Description
Name
Assets
The total number of assets being processed. This value will not be
displayed until all the assets for the given package or all TN document
types have been counted.
Status
98
Starting
Counting
Counted
Extracting
Field
Description
Publishing
Complete
The following summary fields are displayed at the bottom of the screen:
Field
Description
Status
Assets
Duration
The time (in hh:mm:ss) spent executing the most recent publication
or retraction request.
99
100
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
102
Locking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
104
Unlocking Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
108
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
113
116
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 Developers 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 Developers 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 Storing Services in a Version Control System in the
Software AG_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 elements 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 elements 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 elements 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.
102
Status
Can I edit?
Not locked
No
Locked by you
Yes
N/A
No
No
103
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 105.
104
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 105.
You cannot lock a listener or connection element.
To lock elements
1
In the Navigation panel, select the elements that you want to lock.
105
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
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.
Unix system.
106
In the Navigation panel, select the element for which you want to view the status.
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.
Locking Status dialog box
107
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 108.
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.
108
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.
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.
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 elements tab or title
bar and then click Unlock.
To unlock all elements to which you own the lock, use the ToolsMy Locked
Elements command.
109
Click View Locked Elements. The following screen appears, showing all elements that
have user locks and system locks.
Locked Elements screen
localhost means the
machine on which the
110
Locked by System. Lists elements whose corresponding files are marked read-only
on the server file system. You cannot remove a system lock via the Server
Administrator. On the servers file system, you must make the elements files
writable and reload the package. For details, see Unlocking a System Locked
Element on page 111.
Locked by Current User. Lists elements that are locked by you, the server
administrator (or the username with which you logged on to the Integration
Server Administrator). Before you unlock an item, make sure that you have saved
all changes to the server.
Locked by Other Users. Lists elements that are locked by other users on the server.
Before you remove a users lock, make sure that the user has saved all changes to
the server. If not, the user will lose all changes that they made to the element since
they last saved it to the server.
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 Administrators view of locked elements.
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 Elements
Corresponding Server Files on page 112.
On the servers file system, remove the read-only properties from the files that
correspond to the element to make the files writable.
111
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.
In the Navigation panel, select the elements for which you want to view the server file
names.
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.
112
On the Tools menu, click Options. The Options dialog box appears.
Click General.
Under Navigation Panel, select the Automatically unlock upon save check box.
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
113
114
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
Edit the ACL assigned for Write access to the element, to give you access.
Other Problems
I cant 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 113.
I cant 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.
115
116
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
118
121
124
125
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
126
117
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 or a Web service descriptor.
For more details about these types of access, see webMethods Administering Integration
Server.
118
Purch:SubmitPO
Purch:SubmitPO
INVOKE Purch:LogPO
INVOKE Purch:CreditAuth
INVOKE Purch:SendPO
Stage
2
3
4
Purch:LogPO
Purch:CreditAuth
Purch:SendPO
Description
119
Stage
Description
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: If the security settings for the Purch:LogPO, Purch:CreditAuth, or Purch:SendPO
services specify that ACL checking occurs every time the service is invoked (Enforce
execute ACL option is set to Always), webMethods Integration Server would perform
ACL checking when the externally invoked service (Purch:SubmitPO) invoked these
services. For more information about requiring ACL checking, see Assigning ACLs
to Elements on page 121.
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.
120
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 webMethods
Administering Integration Server.
In the Navigation panel, click the package or folder to which you want to assign an
ACL.
In the editor, click the title bar of the package or folder to give it the focus.
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 122.
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.
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.
To assign an ACL to other elements in the Navigation panel
To
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 webMethods
Administering Integration Server.
121
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 122.
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.
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.
Field / Button
Description
List ACL
Users in the Allowed list of this assigned ACL can see that the element
exists and view the elements metadata (input, output, etc.).
Read ACL
Users in the Allowed list of this assigned ACL can view the source code
and metadata of the element.
Write ACL
Users in the Allowed list of this assigned ACL can lock, edit, rename,
and delete the element.
Execute ACL
Users in the Allowed list of this assigned ACL can execute the service.
This level of access only applies to services and Web service descriptors.
122
Field / Button
Description
Enforce
execute ACL
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.
123
Field
Description
ACLs
User Group
Association for
[ACL]
Resulting Users
for [ACL]
124
The names of users that the ACL authorizes, given the current
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 webMethods
Administering Integration Server.
125
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 113 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 cant 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 cant 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.
126
127
128
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
130
A Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
134
135
137
142
145
155
157
159
169
129
Basic Concepts
To successfully build a flow service, you should understand the following basic concepts
and terms.
Purch:SubmitPO
Purch:SubmitPO
INVOKE Purch:GetOrders
INVOKE Purch:LogOrder
INVOKE Purch:CreditAuth
INVOKE Purch:PostPO
...which performs a
sequence
of four services
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.
130
INVOKE Purch:GetOrders
A LOOP step
repeats a set
of
flow steps
LOOP PurchaseOrders
INVOKE Purch:LogOrder
INVOKE Purch:CreditAuth
A BRANCH step
selects a specified
flow step for
execution
BRANCH AuthOK
INVOKE Purch:PostPO
INVOKE Purch:BouncePO
Data-Handling Steps
MAP
131
Control Steps
BRANCH
LOOP
REPEAT
SEQUENCE
EXIT
See Appendix 17, 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.
132
The pipeline holds the input and output for a flow service
Flow Service
The Pipeline
input
ONum:46-77135
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
INVOKE Purch:ConvertDate
Date:04/04/99
Item:PK8801-NS
OrderDate:19990404
output
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.
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).
133
A Process Overview
Building a flow service is a process that involves the following basic stages:
Stage 1
Stage 2
Stage 3
Stage 4
Stage 5
Stage 6
Stage 7
The remaining sections in this chapter and the following chapters provide detailed
information about each stage.
134
To...
Empty Flow
Receive an XML
Document
135
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
136
Link data to and/or from the service using Developers Pipeline tab.
Validate the input and output values of the service at run time.
Declaring parameters makes the input and output requirements of your service known to other
developers who may want to call your service from their programs.
For these reasons, we strongly recommend that you make it a practice to declare input
and output parameters for every service that you create.
137
138
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 19, 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 PublishSubscribe Developers Guide. For more information about creating JMS triggers, see
Using webMethods Integration Server to Build a Client for JMS.
139
Make sure the variables match the data types of the variables they represent in the flow. For
example, if a service produces a String called AuthorizationCode, make sure you define
that variable as a String. Or, if a service produces a Long object called EmployeeID,
define that output variable as an Object and apply the java.lang.Long object
constraint to it. For a complete description of the data types supported by a service,
see Appendix 19, Supported Data Types.
Declared output variables appear automatically as outputs in the pipeline. When you select the
last service or MAP step in a flow, the declared output variables appear under Pipeline
Out.
...and output
parameters on
this side.
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 services 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.
140
By typing the fully qualified name of the IS document type in the Input or Output
field
By clicking
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.
Manually insert input and output variables. Use
to specify the data type and name for
each input and output variable for the service.
To declare input and output parameters for a service
1
Open the service for which you want to declare input and output parameters.
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.
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.
141
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 halfs large white text box.
Click
With the variable selected, set variable properties and apply constraints in the
Properties panel (optional).
If the variable is a document or a document list, repeat steps bd to define and set
on the toolbar and select the type of variable that you want to define.
to indent each
If you want to enter any notes or comments about the input and output parameters,
type your comments on the Comments tab.
142
In the editor, click the services title bar to give the service the focus.
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.
In the Type list, do one of the following to specify the format for the output template:
To...
Select...
html
xml
wml
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/xhdml).
143
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.)
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
Developers Guide.
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 Developers 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.
Note: The File Encoding you select limits the characters that you can use in your
template (including the data inserted into your template using %VALUE%
statements) to those in the character set of the encoding you choose. It also limits
any translated versions of the templates to the same character set. Generally it is a
good idea to use the UTF-8 (Unicode) encoding, since Unicode supports nearly all
of the characters in all of the world's languages. You will not lose any data if you
choose to save your template in UTF-8; any data entered into a form will be
properly interpreted by the Integration Server.
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.
144
145
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.
To configure a services run-time state
1
In the editor, click the services title bar to give the service the focus.
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.
146
147
the Integration Server Administrator and then adjusting your caching values accordingly
.
148
Note: The cache may not be refreshed at the exact time the last hit fulfills the Prefetch
activation requirement. It may vary from 0 to 15 seconds, according to the cache
sweeper thread. For details, see the watt.server.cache.flushMins setting in
webMethods Integration Server.
To enable caching of pipeline contents after a service is invoked
1
In the editor, click the services title bar to give the service the focus.
In the Runtime category of the Properties panel, set Cache results to True.
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.
In the Prefetch activation property, specify the minimum number of hits needed to
activate the use of prefetch.
149
You can also enable the Integration Server to recognize custom locales. By default, the
service uses the null locale. That is, it uses no locale policy.
To specify the execution locale of a service
1
In the editor, click the services title bar to give the service the focus.
In the Runtime category of the Properties panel, do one of the following to specify the
Execution Locale property:
150
Select...
To...
[root locale]
If you selected Open locale editor, complete the following in the Define Custom Locale
dialog box.
In this field...
Do the following...
Language
Select one of the ISO 639 codes that represent the language. (2or 3-letter codes)
Extended Language
Script
Region
IANA Variant
Click OK. The Integration Server will execute the service in the specified locale.
http://IS_server:5555/invoke/folder.subFolder/serviceName
Item
Description
Identifies the webMethods Integration Server on which the service you want
to invoke resides.
Specifies the path portion of the URL, which includes the invoke directive
invoke. The path also identifies the folder in which the service resides and
the name of the service to invoke. Separate subfolders with periods. These
fields are 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.
To create an alias for a service URL, use the HTTP URL alias property in the Properties
panel. When you specify an alias in the HTTP URL alias property and save the service,
Integration Server creates an HTTP path alias for the service URL. The target of the alias
is the path that invokes the service. The path alias is the string that you entered in the
property field.
For example, if the name of the service is folder.subFolder:serviceName, then the path to
invoke the service is invoke/folder.subFolder/serviceName. If you enter "test" in the HTTP
URL alias property and save the service, then the two following URLs will point to the
same service:
http://IS_server:5555/invoke/folder.subFolder/serviceName
http://IS_server:5555/test
151
When creating a path alias for a service, keep the following in mind:
When you add, edit, or delete an HTTP URL alias property in a service, the property is
automatically updated on the Integration Server when the service is saved.
Integration Server stores the HTTP URL alias information in the node.ndf file of the
service. Because the property is encoded in the node.ndf file, it is propagated across
servers through package replication.
URL aliases for services are saved in memory on the Integration Server. The server
checks for URL aliases before processing HTTP requests.
When specifying the alias URL, you must spell it exactly as it is defined on the server.
Alias URLs are case sensitive.
In the editor, click the services title bar to give the service the focus.
In the Runtime category of the Properties panel, next to the HTTP URL alias property,
enter an alias string for the URL that will invoke the service.
Important! Do not use reserved characters in the URL alias string. Alias strings that
contain reserved characters are invalid and will not work.
152
In the editor, click the services title bar to give the service the focus.
In the Runtime category of the Properties panel, next to the Pipeline Debug property,
select Save.
When you run the service, the contents of the pipeline are saved to a file on
webMethods Integration Server. The file is saved as folderName.serviceName.xml in the
IntegrationServer_directory\pipeline directory. If the file does not exist, the service
creates it. If the file already exists, the service overwrites it.
153
In the editor, click the services title bar to give the service the focus.
In the Runtime category of the Properties panel, next to the Pipeline Debug property,
select one of the following options:
Select...
To...
Restore (Override)
Restore (Merge)
Merge the pipeline with one from a file when the service
executes.
When this option is selected and the input parameters in the file
match the input parameters in the pipeline, the values defined
in the file are used in the pipeline. If there are input parameters
in the pipeline that are not matched in the file, the input
parameters in the pipeline remain in the pipeline.
When the service executes, the server loads the pipeline file,
folderName.serviceName.xml, from the IntegrationServer_directory\pipeline directory.
Note: The server will throw an exception at run time if the pipeline file does not
exist or cannot be found. To learn how to save the service pipeline using the
Pipeline Debug property, see Using the Pipeline Debug Property to Save the
Service Pipeline on page 153.
154
Note: If service auditing is also configured for the service, the Integration Server adds
an entry to the service 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 service
log entry for the service will have a status of Failed and will display the actual error
message.
155
When you configure service retry, the Integration Server verifies that the retry period for
that service will not exceed the maximum retry period. The Integration Server determines
the retry period for the service by multiplying the maximum retry attempts by the retry
interval. If this value exceeds the maximum retry period, Developer displays an error
indicating that either the maximum attempts or the retry interval needs to be modified.
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.
The service retry period must be less than the maximum retry period. For more
information, see About the Maximum Retry Period on page 155.
To configure service retry
1
Open the service for which you want to configure service retry.
In the editor, click the services title bar to give the service the focus.
156
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.
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.
157
Local names follow the same construction rules as NCNames in XML. 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
gnrent
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 or document
type by specifying both a namespace name and a local name in the Properties panel.
An implicit universal name is automatically derived from the name of the service or
document type itself, and it acts as the universal name when an explicit universal
name has not been specified. The server derives an implicit name as follows:
The namespace name is the literal string http://localhost/ followed by the fully
qualified name of the folder in which the service or document type resides on the
Integration Server.
The local name is the unqualified name of the service or document type.
Open the service or document type whose universal name you want to assign, edit, or
view.
In the editor, click the services or document types title bar to give the service or
document type the focus.
158
If you want to assign or edit a universal name, specify the following in the Universal
Name category of the Properties panel:
In this field...
Specify...
Namespace name
The URI that will be used to qualify the name of this service or
document type. You must specify a valid absolute URI.
Local name
Open the service or document type whose universal name you want to delete.
In the editor, click the services or document types title bar to give the service or
document type the focus.
In the Universal Name category of the Properties panel, clear the settings in the
Namespace name and Local name fields.
159
Note: When the Integration Server logs an entry for a service, the log entry contains
the identity 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 services
Properties panel. These properties determine when a service generates audit data and
what data is stored in the service 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 service log.
Whether to include a copy of the service input pipeline in the service log.
Audit properties for a service
Specifies if a service
generates audit
data.
Specifies when to
include the pipeline
in the service log.
Specifies when a
service generates
audit data during
execution.
Keep in mind that generating audit data can impact performance. The Integration Server
uses the network to send the audit data to the service log and uses memory to actually
save the data in the service 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 service log can be stored in 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 service
log whether it is in a flat file or a database. If the service log is in 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 service log exists. For more information about the service log, see
the webMethods Audit Logging Guide.
160
Description
Never
Always
161
Log on option
Description
Error only
The service generates audit data only when the service ends because
of a failure. If the service executes successfully, it will not generate
audit data.
Performance Impact: This option impacts performance only when the
service fails. When a service executes successfully, this option does
not impact performance. This option offers the smallest performance
impact of all the options under Log on.
Error and
success
The service generates audit data when the service finishes executing,
regardless of whether it ends because of success or failure. The service
log will contain an entry for every time the service finishes processing.
Performance Impact: This option impacts performance every time the
service executes, whether it ends because of error or success. If you
are concerned only with services that fail, consider using the Error only
option instead.
Error, success,
and start
The service generates audit data when it begins executing and when it
finishes executing. When the service executes to completion, the
service log will contain a start entry and an end or error entry.
Generally, most services execute fairly quickly. By the time an
administrator views the service log using webMethods Monitor, the
service log would probably contain entries for the start and end of
service execution. Situations where you might want the service to
generate audit data at the start and end of service execution include:
To check for the start of long-running services
To detect service hangs.
In both situations, if service execution began but did not complete, the
service 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 service 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.
162
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 toplevel service only is selected and the service is not the root service in the flow service, it
will not generate audit data.
The service 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 service log will
not contain a copy of the input pipeline.
Note: Including the pipeline in the service log is more beneficial when the service log
is stored in a database. The Integration Server can save the pipeline to a flat file
service log; however, you will not be able to use the pipeline data to reinvoke the
service or perform failure analysis.
163
The following table describes the options in the Include pipeline property on the Properties
panel. Keep in mind that saving the input pipeline to the service log can impact the
performance of the Integration Server.
Include pipeline
Description
Never
The Integration Server will never save a copy of the services input
pipeline to the service log. Select this option if you are using a flat file
for the service 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 service log.
On errors only
The Integration Server saves a copy of the input pipeline to the service
log only when the service generates audit data because of failure.
Select this option if you want to use the resubmission capabilities of
the webMethods Monitor to reinvoke a failed service. For more
information about webMethods Monitor, see the webMethods
Monitor documentation.
Performance Impact: For successful service invocations, the On errors only
option requires minimal network bandwidth. Service invocations that
end in failure require more network bandwidth because the
Integration Server must save the audit data and the input pipeline.
The actual network bandwidth needed depends on the size of the
initial input pipeline. A large pipeline can degrade performance
because it may negatively impact the rate at which the data is saved to
the service log.
164
Include pipeline
Description
Always
The Integration Server saves a copy of the input pipeline to the service
log every time the service generates audit data. If the service
generates data at the start and end of execution (Log on is set to Error,
success, and start), the input pipeline is saved with the service log entry
for the start of service execution. If a service does not generate audit
data, the Integration Server does not include a copy of the input
pipeline.
Select the Always option if you want to be able to use the resubmission
capabilities of the webMethods Monitor to reinvoke the service,
regardless of whether the original service invocation succeeded or
failed. Including the pipeline can be useful if a resource experiences a
fatal failure (such as hard disk failure). To restore the resource to its
pre-failure state, you could resubmit all the service invocations that
occurred since the last time the resource was backed up. This is
sometimes called a full audit for recovery.
Performance Impact: The Always option is the most expensive option
under Include pipeline. This option places the greatest demand on
network bandwidth because the Integration Server must write a copy
of the input pipeline to the service log every time a service executes.
The actual network bandwidth needed depends on the size of the
initial input pipeline. A large input pipeline can negatively impact the
rate at which the data is saved to the service 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 service log to track and reinvoke failed services. To use the
service log for error auditing, services must generate audit data when errors occur, and
the Integration Server must save a copy of the services input pipeline in the service 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.
165
To make sure the service log contains the information needed to perform error auditing,
select the following Audit properties.
For this property...
Enable auditing
Include pipeline
On errors only
Log on
Error only
To use the service log for error auditing, store the service log in a database.
Service Auditing
When you perform service auditing, you use the service log to track which services
execute successfully and which services fail. You can perform service auditing to analyze
the service log and determine how often a service executes, how many times it succeeds,
and how many times it fails. To use the service log for service auditing, services need to
generate audit data after execution ends.
To make sure the service log contains the information needed to perform service
auditing, select the following Audit properties.
For this property...
Enable auditing
Include pipeline
Never
Note: Configure a service to save a copy of the input
pipeline only if you intend to reinvoke the service using
the resubmission capabilities of the webMethods
Monitor.
Log on
To use the service log for service auditing, you can store the service log in either a flat file
or a database.
166
Enable auditing
Include pipeline
Always
Log on
To use the service log to audit for recovery, store the service log in a database.
167
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.
In the editor, click the services title bar to give the service the focus.
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 161.
For Include pipeline, select an option to indicate when the Integration Server should
include a copy of the input pipeline in the service 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 Service Log on page 163.
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 161.
168
Audit Level in
Developer 4.x
Enable auditing
Include pipeline
Log on
None
Never
Never
--
Brief
Always
Never
Verbose
Always
Always
Input/Output
parameters
Details of each
flow step
169
If you want to print the flow, select your browsers 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.
170
172
173
177
180
190
196
198
202
205
171
172
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...
INVOKE step
177
MAP step
205
BRANCH step
180
173
To insert a/an...
LOOP step
198
REPEAT step
190
SEQUENCE step
196
EXIT step
202
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.
174
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.
To...
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)
175
Although each type of flow step has a set of unique properties, they all have the
following properties:
Property
Description
Comments
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 180 and The EXIT Step on page 202
for additional information about this use of the label property.
For a complete description of the properties associated with each flow step, see
Appendix 17, webMethods Flow Steps.
176
purchasing.orders:getOrders
You must specify the services name exactly as it is defined on the server. Service
names are case sensitive.
177
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.
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.
178
Specify...
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 services fully
qualified name in the format folderName:serviceName or click
and select a service from the list.
Timeout
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 284.
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 284.
If necessary, on the Pipeline tab, link Pipeline In variables to Service In variables. Link
Service Out variables to Pipeline Out variables. For more information about linking
variables to a service, see Linking Variables on page 213.
Tip! When you install Developer, the
Insert menu displays a list of commonly
used services. You can use the ToolsOptions command to customize this list of
services to suit your needs.
179
Create a list of the conditional steps (target steps) and make them children of the
BRANCH step.
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 181.
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 181.
180
Each conditional
step has a label
that matches the
value that causes
it to execute.
181
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 184.
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 184.
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 185.
182
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.
In the Properties panel for the BRANCH step, set Evaluate labels to True.
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 20, 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 185.
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).
183
Do the following...
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
string
Leave the Label property blank (empty). At run time, the BRANCH
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.
Important! If you branch on expressions (Evaluate labels is set to True), you cannot
branch on null or empty values. When executing the BRANCH step and evaluating
labels, the server ignores target steps with a blank or $null label.
The following example shows a BRANCH step used to authorize a credit card number
based on the buyers 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.
184
BRANCH that contains target steps to match null values or empty strings
185
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.
186
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 196.
187
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.
Click
Scope
Timeout
Label
188
Switch
Evaluate labels
Insert the conditional steps that belong to the BRANCH (that is, its children) using
the following steps:
a
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...
A string
A constrained
object value
A regular
expression
Example /^REL/
An empty string
A blank field
A null value
$null
Any unmatched value (that is, execute the step if the value
does not match any other label)
$default
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.
189
FAILURE
Re-executes the set of child steps if any step in the set fails.
SUCCESS
190
-1 or blank
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
FAILURE
If the REPEAT step is a child of another flow step, the failure is propagated to its parent.
191
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. The variable you
specify must be a String.
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 dont 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.
To build a REPEAT step that re-executes failed steps
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.
Click
192
Specify...
Comments
Scope
Specify...
Timeout
Label
Count
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%). The variable you specify must be a String.
Repeat on
FAILURE
193
Beneath the REPEAT step, use the following steps to insert each step that you want to
repeat:
a
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.
Click
194
Specify...
Comments
Scope
Specify...
Timeout
Label
Count
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%). The variable you specify must be a
String.
Repeat on
SUCCESS
195
Beneath the REPEAT step, use the following steps to insert each step that you want
repeat:
a
Set Exit on to
FAILURE
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.
196
Set Exit on to
SUCCESS
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
sequence fails.
DONE
197
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.
Nested LOOP steps
The entire
LOOP step
is a child of the
outer LOOP.
198
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.
199
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.
Click
200
Specify
Comments
Scope
Specify
Timeout
Label
Input array
Output array
The name of the element that you want the server to collect
each time the LOOP executes. You do not need to specify this
property if the loop does not produce output values or if you
are collecting the elements of Input array.
201
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.
202
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.
When 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.
Click
Label
Exit from
The flow step from which you want to exit. Specify one of the
following:
Specify
$loop
$parent
$flow
Entire flow.
203
Signal
Failure message
To
SUCCESS
FAILURE
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%).
The variable you specify must be a String.
This property is not used when Signal is set to SUCCESS.
204
205
206
208
208
213
233
207
208
This stage...
1
Represents...
The expected state of the pipeline just before the selected service
executes.
Pipeline In depicts the set of variables that are expected to be in the
pipeline before the service executes (based on the declared input
and output parameters of the preceding services).
Service In depicts the set of variables the selected service expects as
input (as defined by its input parameters).
On the Pipeline tab, you can insert pipeline modifiers at this stage
to adjust the contents of the pipeline to suit the requirements of the
service. 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 before the service executes at run time.
209
This stage...
2
Represents...
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 279.
210
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 235.
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.
211
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:
Use this modifier...
Link
Drop
Set Value
To...
Link a pipeline variable to a service variable. The Link modifier lets you
resolve variable-name and data-structure differences by linking
(copying) the value of one variable to another at run time. For
information about using this pipeline modifier, see Linking
Variables on page 213.
Drop a variable from the pipeline. The Drop modifier removes
extraneous variables from the pipeline. For information about
using this pipeline modifier, see Dropping Variables from the
Pipeline on page 231.
Assign a value to a variable. The Set Value modifier hard codes a
value for a variable. For information about this pipeline modifier,
see Assigning Values to Pipeline Variables on page 227.
Open the flow service for which you want to print the Pipeline tab.
In the editor, select the INVOKE or MAP step for which you want to print the Pipeline
tab.
Scroll or resize the Pipeline tab to display the portion of the pipeline you want to view
as HTML.
212
If you want to print the pipeline, use your browser's print command.
See page...
Linking variables
213
220
222
225
225
227
231
232
64
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.
213
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.
Linking the pipeline to service input
When a pipeline
variable name is
different from the one
used by the service,
use the Link modifier
to connect them.
214
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 services 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.
Linking service output to the pipeline
Developer automatically
adds a services 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.
215
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 217.)
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 222. For more information about placing conditions on links between
variables, see Applying Conditions to Links Between Variables on page 225.
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.
To create a link between variables
1
In the editor, select the INVOKE or MAP step containing the variables you want to
link.
If you want to create a link between a variable in Pipeline In and one in Service In, do the
following:
In Pipeline In, click the pipeline variable you want to use as the source variable.
In Service In, click the input variable you want to use as the target variable.
Click
on the toolbar.
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.
In Pipeline Out, click the pipeline variable you want to use as the target variable.
Click
on the toolbar.
Notes:
216
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 222.
If you want to place a condition on the execution of the link, see Applying
Conditions to Links Between Variables on page 225.
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.
Tip! To scroll through the Pipeline In and Pipeline Out trees independently, display the
left-hand scroll bar. Click
to display the left-hand scroll bar. Click
to hide the
left-hand scroll bar. The left-hand scroll bar is only available on the Pipeline tab for a
MAP step. When you expand a transformer, Developer hides the left-hand scroll bar
automatically.
217
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
218
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.
219
220
When you link between scalar and array variables, you can specify which element of
the array variable you want to link to or from. Scalar variables are those that hold a
single value, such as String, document, and Object. Array variables are those that hold
multiple values, such as String list, String table, document list, and Object list. For
example, you can link a String to the second element of a String list. Alternatively, you
can link the second element in a String list to a String.
When you link between scalar and array variables and you do not specify which
element in the array variable that you want to link to or from, Developer uses the
default behavior to determine the value of the target variable.
For more information about the default behavior for linking array variables, see Default
Pipeline Rules for Linking to and from Array Variables on page 444.
Examples of Structural Transformations on the Pipeline Tab
The structural transformations you can perform by linking variables on the Pipeline tab
can be more complex than transforming a String to a String list. For example, you can
combine two String lists into one document list through linking. The following section
explains a common structural transformation that you can complete via linking in the
pipeline.
Converting a String List to a Document List
You can convert a String list to a document list using the Pipeline tab. In the following
diagram, aList is the String list you want to convert to a document list. The variable
documentList is the document list to which you want to copy the values contained in the
String list. documentList has a String child aString. To convert the String list to a document
list, link aList to aString.
Converting a String list to a document list
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.
221
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 233. For more information about built-in services,
see the webMethods Integration Server Built-In Services Reference.
222
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 propertys 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
223
Create a link between the variables using the procedure described in To create a link
between variables on page 216.
224
On the Properties panel, click the Indices propertys Edit button. Developer displays
the Link Indices dialog box.
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.
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.
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.
On the Pipeline tab, select the link that you want to delete.
225
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.
Linking Multiple Source Variables to a Target Variable
By applying conditions to the links between variables, you can link more than one source
variable to the same target variable. When you draw more than one link to the same
target variable, at most, only one of the conditions you apply to the links can be true at
run time. The conditions must be mutually exclusive.
At run time, webMethods Integration Server executes all conditional links whose
conditions evaluate to true. If more than one conditional link to the same target variable
evaluates to true, the value of the target variable will be the result of whichever link
executes last. Because the order in which links are executed at run time is not guaranteed,
the final value of the target variable may vary.
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 180.
226
Create a link between the variables using the procedure described in To create a link
between variables on page 216.
On the Properties panel, set the Evaluate copy condition property to True.
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 20, 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 318.
227
To view (or change) the value that is assigned to the Set Value modifier, double-click the
icon next to the variables name to open the Input For dialog box.
Input For dialog box
Specify the value that
you want the server to
assign to this variable
at run time.
icon.
228
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.
229
In the editor, select the INVOKE or MAP step containing the variable you want to
alter.
Click
In the Input For dialog box, specify the value you want to assign to this variable.
on the toolbar.
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.
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.)
230
In the editor, select the INVOKE or MAP step containing the variable with the value
you want to copy and paste.
Select the
Select the variable or variables to which you want to assign the copied value,
right-click and select Paste.
Note: You can only copy and paste values for variables that are in Service In or Pipeline
Out.
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.
231
In the editor, select the INVOKE or MAP step whose pipeline variables you want to
drop.
Click
on the toolbar.
Note: You can only drop variables from Pipeline In and Pipeline Out. In a MAP step, you
can only drop variables from Pipeline In.
232
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.
Select the point where you want to add the new variable.
Note: In an INVOKE step, you can add a new variable to Pipeline In, Service In,
Service Out, or Pipeline Out. In a MAP step, you can only add new variables in
Pipeline Out.
Click
If the variable is a document or a document list, repeat steps 4 and 5 to define its
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.)
233
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.
MAP step with transformers
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.
234
Contains services to
pub.date
pub.document
pub.list
pub.math
pub.string
For more information about built-in services, see the webMethods Integration Server BuiltIn Services Reference.
235
To insert a transformer
1
In the editor, select the MAP step in which you want to insert a transformer.
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.
Select the transformer and, in the Properties panel, set its properties:
For this property...
Specify...
Service
Validate input
Validate output
Click OK.
For information about debugging transformers, see Debugging Transformers on
page 243.
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.
236
In Pipeline In, select the variable you want to use as input to the transformer and
drag your mouse to the transformer.
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.
Repeat steps a and b for each transformer input variable you want to link to a
pipeline variable.
Note: You can assign a value to a transformer input variable using the Set Value
modifier
. To assign an input value to a transformer, first expand the
transformer by double-clicking the transformer name, by clicking
ComposeExpand, or by clicking
next to the transformer.
237
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.
In the Link From list, select the transformer variable that you want to link to the
selected Pipeline Out variable.
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.
238
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.
unitPrice cannot be linked to num1 because of dimensionality differences
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.
239
In the editor, select the MAP step containing the transformer you want to validate.
Under Transformers, select the transformer for which you want to validate input or
output.
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.
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.
Click OK.
240
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.
Under Transformers, select the transformer service you want to copy. Right-click the
transformer and then select Copy.
To paste the transformer, click anywhere under Transformers. Right-click and select
Paste.
Link the input and output variables of the transformer using the procedures
described in Linking Variables to a Transformer on page 237.
241
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.
Pipeline tab with an expanded transformer
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.
Note: If you expand a transformer, you can use the Set Value modifier to assign a value
to a variable in Service In.
To expand and collapse the contents of a 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.
242
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 49.
To rename a transformer
1
Use the Navigation panel to determine the new name or location of the service called
by the transformer.
Open the flow service containing the transformer you want to rename.
In the editor, select the MAP step containing the transformer. Then, on the Pipeline tab,
select the transformer you want to rename.
In the Service property on the Properties panel, delete the old name and type in the
services 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 312.
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 313.
Disable a transformer so that it does not execute at run time. For more information
about disabling transformers, see Disabling Transformers on page 317.
Note: You can also use the Pipeline debug property when testing and debugging the
flow service to view the activity of a transformer. The Pipeline debug property
enables you to easily test another service against the current set of pipeline values or
if you want to restore the pipeline to this exact state later in the debugging process.
243
244
Creating an IS Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
246
256
Creating a Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
273
245
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.
Content constraints in an IS schema describe the type of information that elements and
attributes can contain in a valid instance document. For example, the <quantity>
element might be required to contain a value that is a positive integer.
During data validation, the validation engine in webMethods Integration Server
compares the elements and attributes in the instance document with the structural and
content constraints described for those elements and attributes in the IS schema.The
validation engine considers the instance document to be valid when it complies with the
structural and content constraints described in the IS schema. For more information
about data validation, see Chapter 10, Performing Data Validation.
You can create IS schemas from an XML schema, a DTD (Document Type Definition), or
an XML document that references an existing DTD. For information about creating IS
schemas, see Creating an IS Schema on page 251.
246
Schema editor
Specifies the target
namespace to
which the schema
belongs.
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.
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.
247
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.
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.
248
Symbol
Description
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.
249
If you select an
element
declaration...
When you select a simple type definition, the schema details area looks like the following:
Schema details area for a simple type definition
250
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
In the New dialog box, select Schema, and then click Next.
In the New Schema dialog box, next to Folder, select the folder where you want to save
the IS schema.
251
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 47.
In the New Schema dialog box, select one of the following to specify the source for the
IS schema.
Specify...
To...
XML
DTD
XML
Schema
Important! You can create an IS schema from an XML document only if the XML
document references an existing DTD.
6
Click Next.
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
Under Schema domain, specify the schema domain to which the generated IS schema
will belong. Do one of the following:
To add the IS schema to the default schema domain, select Use default schema
domain.
To add the IS schemas to a specified schema domain, select Use specified schema
domain and provide the name of the schema domain in the text box. A schema
domain name must be a string that is a valid name of an element in Integration
Server. For more information about naming restrictions for Integration Server
elements, see Guidelines for Naming Elements on page 48.
For more information about schema domains, see About Schema Domains on
page 251.
252
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 23, 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 507.
253
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.
254
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 255.
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 255.
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.
To edit a simple type definition
1
Open the IS schema that contains the simple type you want to edit.
In the schema browser area of the editor, select the simple type that you want to edit.
The
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 483.
255
You can view the constraining facet values set in the type definitions from which a simple
type was derived by clicking the Base Constraints button. Base constraints are the
constraining facet values set in all the type definitions from which a simple type is
derivedfrom the primitive type to the immediate parent type. These constraint values
represent the cumulative facet values for the simple type.
When you edit the constraining facets for a simple type definition, you can only make the
constraining facets more restrictivethe applied constraining facets cannot become less
restrictive. For example, if the length value is applied to the simple type, the maxLength or
minLength values cannot be set because the maxLength and minLength facets are less
restrictive than length.
256
In the New dialog box, select Document Type and click Next.
In the list next to Folder, select the folder in which you want to save the IS
document type.
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 47.
Click Next.
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.
Click Finish.
Click
on the toolbar and select the type of field that you want to define.
257
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 272. For information about applying constraints, see
Applying Constraints to Variables on page 279.
If the field is a document or a document list, repeat steps ac to define and set the
properties and constraints for each of its members. Use
field beneath the document or document list field.
258
A document defined inline. Integration Server inserts a document field for the
global element in the IS document type. The document field contents correspond
to the content model of the global element. This is the default.
259
Integration Server can create separate IS document types for named complex types or
expand document types inline within one document type. For more information, see
Expanding Complex Document Types Inline on page 260.
Integration Server generates a separate IS document type for any referenced complex
type and generates an IS document type for any types derived from the referenced
complex types.
Integration Server can create one field for a substitution group or create fields for
every member element in a substitution group. For more information, see
Generating Fields for Substitution Groups on page 262.
Expanding Complex Document Types Inline
Integration Server processes complex types from an XML schema in one of two ways,
depending on an option you select when you create a new IS document type. One way is
to expand the complex type as an inline document type in the editor. The other way is
to generate a separate IS document type for each complex type in the schema, with
references to those document types.
Example XML Schema
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://usecases/xsd2doc/01"
xmlns:uc="http://usecases/xsd2doc/01" >
<xsd:element name="eltA" type="uc:documentX" />
<xsd:complexType name="documentX">
<xsd:sequence>
<xsd:element name="eltX_E" type="xsd:string" />
<xsd:element name="eltX_F" type="uc:documentY" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="documentY">
<xsd:sequence>
<xsd:element name="eltY_G" type="xsd:string" />
<xsd:element name="eltY_H" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
260
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:
Complex types expanded inline
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 typesone 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):
Complex types generated as separate document types
261
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.)
Generating Fields for Substitution Groups
Integration Server processes substitution group elements in one of two ways, depending
on the value of the watt.core.schema.generateSubstitutionGroups property:
When this property is set to true, the schema processor imports all substitution group
members (head element and substitutable elements) as optional fields, even though
they are defined as required elements in the XML schema definition.
When this property is set to false, the resulting document type contains a field that
corresponds to the head element in the substitution group, but does not contain any
elements for members of the substitution group. This is the default.
If the head element is declared as abstract, the Integration Server does not include that
element in the IS document type.
To create an IS document type from an XML document, DTD, or XML schema
1
In the New dialog box, select Document Type and click Next.
262
In the list next to Folder, select the folder in which you want to save the IS
document type.
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 47.
Click Next.
To...
XML
DTD
XML Schema
Click Next.
In the Enter the URL or select a local file field, do one of the following:
If you want to base the IS document type on a file 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 document type on a file that resides on your local file
system, type in the path and file name, or click
file.
Under Schema domain, specify the schema domain to which any IS schemas generated
will belong. Do one of the following:
To add the IS schema to the default schema domain, select Use default schema
domain.
To add the IS schemas to a specified schema domain, select Use specified schema
domain and provide the name of the schema domain in the text box. A schema
domain name must be a string that is a valid name of an element in Integration
Server. For more information about naming restrictions for Integration Server
elements, see Guidelines for Naming Elements on page 48.
For more information about schema domains, see About Schema Domains on
page 251.
If you selected XML, click Finish. Developer generates the IS document type using
the XML document you specified and displays it in the editor.
If you selected DTD, click Next. Developer prompts you to select the root element of
the document. Select the root element and click OK. Developer generates the IS
document type and displays it in the editor. Developer also generates an IS
schema and displays it in the Navigation panel.
263
Select the elements that you want to use as the root elements for the IS
document type. The IS document type will contain all of the selected root
elements.
To select multiple elements, press the CTRL key while selecting elements.
Under Complex type processing, select Expand complex types inline if you want
complex types to be expanded within the IS document type. That is, the
complex type will be a document variable within the IS document type.
Select Generate complex types as document types if you want separate IS
document types created for the complex types in the XML schema definition.
The resulting IS document type contains document references in place of a
document variable for the complex type.
Select the Generate all element references as document type references check box if
you want Integration Server to replace all references to global elements with
document references even if the element is referenced only once. Integration
Server generates an IS document type for each referenced element.
Leave the check box cleared if you want Integration Server to replace an
element reference with a document reference only if the element is referenced
more than once. When an element is referenced only once, Developer replaces
the element reference with a document field.
If you want the IS document type to use different prefixes than those specified
in the XML schema definition, select the prefix you want to change and enter a
new prefix. Repeat for each namespace prefix that you want to change.
The prefix you assign must be unique and must be a valid XML NCName
Click Finish. Developer generates the IS document type(s) and displays them
in the editor. Developer also generates an IS schema and displays it in the
Navigation panel.
Developer creates the IS document type and saves it on the Integration Server.
Developer might create multiple document types depending on the contents of the
source file and the processing options you selected.
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 488.
264
265
Important! If you do not select the Overwrite existing elements when importing referenced
elements check box and the Broker document type references an element with the
same name as an existing Integration Server element, Developer will not create the
publishable document type.
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.
To create an IS document type from a Broker document type
1
In the New dialog box, select Document Type and click Next.
In the list next to Folder, select the folder in which you want to save the IS
document type.
In the Name field, type a name for the IS document type using any combination of
letters, numbers, and/or the underscore character.
Click Next.
Under Select a source, select Broker Document Type, and click Next.
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.
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.
266
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 Developers 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
Developers Guide.
267
You can only delete an _env field from a document type that is not publishable.
The _env field is always the last field in a publishable document type.
For more information about the _env field and the contents of the pub:publish:envelope
document type, see the Publish-Subscribe Developers 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.
268
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 Developers Guide.
269
Open the IS document type you want to print and click its title bar in the editor to
give it the focus.
If you want to print the IS document type, select your browsers print command.
Open the service to which you want to assign the IS document type.
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.
270
Click...
To...
Document Reference
In the Name field, type the fully qualified name of the IS document type or select it
from the list next to Folder.
Click OK.
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.
271
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 279.)
Note: Use the XML Namespace property to assign a namespace name to a field. The
namespace name indicates the namespace to which the field belongs. When
generating XML schema definitions and WSDL documents, the Integration Server
uses the value of the XML Namespace field along with the field name (the local name) to
create a qualified name (QName) for the field. For more information about setting the
XML Namespace property, see the Web Services Developers Guide.
The Text Field, Password, Large Editor, and Pick List options of the String display type property
affect how you input data for the field as follows. These options are not available for
Objects and Object lists.
If you want the input
Select...
Password
272
Select...
Large Editor
This is useful if you expect a large amount of text as input for the
field, or you need to have TAB or new line characters in the input
To be limited to a predefined list of values
Pick List
Use the Pick list choices propertys Edit button to define the values that
will appear as choices when Developer prompts for input at run time.
Note: When executing a service, if you want a null value to be available as the first
option in the Pick List, set the dev.uicontrols.picklist.putNullStringAtTop
configuration parameter in the developer.cnf file located in the
Developer_directory\config directory to true. By default, this configuration parameter
is set to false and Developer adds the null value to the end of the Pick List.
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.)
If the specification resides in a different package than the service, you must set up a
package dependency. For more information about package dependencies, see
Identifying Package Dependencies on page 88.
A specification wholly defines the input and output parameters for a service that
references it. This means that you cannot directly alter the services 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
273
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 services 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
In the list next to Folder, select the folder to which you want to save the
specification.
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
4
Click Finish.
to select it
274
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.
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.
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 halfs large white text box.
Click
With the field selected, set its properties and apply constraints on the Properties
panel (optional).
on the toolbar and select the type of field that you want to specify.
If the field is a document or a document list, repeat steps bd to define each of its
members. Use
field.
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 services Input/Output tab.
275
276
10
278
279
284
287
288
288
289
291
277
278
279
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.
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.
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.
Note: The state of the Allow unspecified fields property determines whether the
document is open or closed. An open document permits undeclared fields
(variables) to exist at run time. A closed document does not allow undeclared
fields to exist at run time. The Integration Server considers a document to be
open if the Allow unspecified fields property is set to True and considers a
document to be closed if the Allow unspecified fields property is set to False.
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 22, 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 282.
280
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 282.
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.
If the selected variable is an Object or Object list, for the Java wrapper type property,
select the Java class for the variable contents. If you do not want to apply a Java
class or if the Java class is not listed, select UNKNOWN.
For more information about supported Java classes for Objects and Object lists,
see Java Classes for Objects on page 441.
Repeat this procedure for each variable to which you want to apply constraints in the
IS document type, specification, service input, or service output.
modifier.
281
The constraining facets you can specify depend on the content type. For more
information about the constraining facets for each content type, see Appendix 19,
Supported Data Types on page 439.
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 254.
To customize a content type
1
Select the variable to which you want to apply a customized content type.
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:
282
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.
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.
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 483.
Click OK. Developer saves the changes as a new content type named
contentType_customized.
Note: The constraining facets displayed below the Content type list depend on the
primitive type from which the simple type is derived. Primitive types are the basic
data types from which all other data types are derived. For example, if the
primitive type is string, Developer displays the constraining facets enumeration,
length, minLength, maxLength, and pattern. For more information about primitive
types, refer to XML Schema Part 2: Datatypes at
http://www.w3.org/TR/xmlschema-2/.
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 23, Validation Errors and Exceptions
Constraint status
Required field.
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 441.
283
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.
284
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 196.
Open the service for which you want to validate input and/or output every time the
service is invoked.
If you want the input of the service validated every time the service executes, select
the Validate input check box.
If you want the output of the service validated every time the service executes, select
the Validate output check box.
Service output
values will not be
validated.
285
In the flow editor, select the INVOKE step containing the service for which you want
Integration Server to validate input and/or output values.
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.
Inputs to the
invoked service
will be validated.
Outputs of the
service will not be
validated.
Important! Keep in mind that the Validate input and Validate output properties are
independent of any validation settings that you might have already set in the service.
If you select the Validate input and/or Validate output check boxes on the Input/Output tab
of the invoked service, then every time the service executes, input/output validation
is performed. If you also specify input/output validation via the INVOKE step,
duplicate validation will result, possibly slowing down the execution of the service.
286
287
288
289
if (dtrCursor.first("boundNode")) {
// assumption here that there's data at the current cursor position
validCursor.insertAfter( "object", dtrCursor.getValue() );
}
dtrCursor.destroy();
// set <conformsTo> parameter to point to the document type to validate against
// This document type must exist on webMethods Integration Server
validCursor.insertAfter( "conformsTo", ifc+":"+rec );
290
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.
291
Start webMethods Integration Server and open the Integration Server Administrator.
Click Edit Extended Settings. The server displays the Extended Settings screen.
292
11
294
Testing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
294
295
304
305
305
Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
313
316
319
321
326
293
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 browserbased clients (especially ones whose output will be formatted using output
templates) you will want to test those services at least once using this technique.
294
On the Test menu, select Run. If you have not yet saved changes to the service,
Developer prompts you to save them.
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 296.
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.
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 298.
Click OK. Developer invokes the service with the specified set of input values.
295
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 299.
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 301.
...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.
296
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.
To enter values by typing them
1
Open the service and execute it as described in Testing Services from Developer on
page 295 or Testing Services from a Browser on page 304.
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.
Use this
To...
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.
If you want Developer to pass empty Strings to the service, select the Include empty
values for String Types check box. When you select this check box, empty Strings are
passed with a zero-length value. If you do not select this check box, empty strings are
not passed to the service.
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.
297
Open the service and execute it as described in Testing Services from Developer on
page 295 or Testing Services from a Browser on page 304.
Enter input values into the Input dialog box as described in Entering Input for a
Service on page 296.
In the Save File dialog box, specify the name of the file to which you want the values
saved.
298
Variables that exist in the Input dialog box, but not in the file, are set to null.
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 321. For information about modifying values in the
pipeline, see Modifying the Current Pipeline on page 319.
To load input values that have been saved to a file
1
Open the service and execute it as described in Testing Services from Developer on
page 295.
When the Input dialog box appears, click Load. The Load File dialog box appears.
Select the file containing the input values that you want to load.
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.
299
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 services 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 321.
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 321. For information about modifying an existing pipeline, see Modifying
the Current Pipeline on page 319.
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 321. For information about
modifying an existing pipeline, see Modifying the Current Pipeline on page 319.
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
objects Java class message.
Variables that contain com.wm.util.Table objects appear as document lists in the Results
panel.
300
Developer inserts
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.)
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 message box.
You can click the Details button to display the call stack and the pipeline at the point
where the error occurred.
Note: The Integration Server logs details about run-time exceptions, including the call
stack, the stack trace, and the cause of the error, in the Integration Server error log. This
information is useful for debugging services in a production environment. You can
control the level of detail written to the log by setting the
watt.server.deprecatedExceptionLogging parameter. For more information about this
parameter and the Integration Server error log, see webMethods Administering Integration
Server.
301
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 72.
This service
threw the
exception.
302
Now lets 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:
Call stack from a deeply nested service
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.
303
On the Test menu, click Run in Browser. If you have unsaved edits, Developer prompts
you to save them.
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 296.
Note: Only Strings and String lists are passed to the browser.
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.
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 298.
Click OK. Developer builds the URL to invoke the service with the inputs you have
specified, launches your browser, and passes it the URL.
304
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.)
From the Test menu, select Send XML File. If you have unsaved edits, Developer
prompts you to save them.
In the Select Test Mode dialog box, specify whether you want the service to run in
Trace mode or Step mode and click OK.
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 299.
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 301.
305
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 308.
Trace to Here
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 309.
Step
Executes the next flow step and then halts. For information about
using this command, see Using the Step Tools on page 310.
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 Through a Child Flow on page 311 and
Using the Step Tools with a MAP Step on page 312.
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.
306
307
Use...
Trace
Trace to Here
Trace to the end of the service or the next breakpoint, including the
paths of all child services that this service invokes
Trace Into
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 125.
To trace to the end of a service
1
308
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.
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 313.
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.
When Developer reaches the selected flow step, it halts. At this point, you may do any
of the following:
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 Reset to clear the debugging session and reset the starting execution point
to the top of the service.
309
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.
Use...
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
within it
Step Into
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 125.
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.
310
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.
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 311 or To trace to a specified
point on page 309 if you need procedures for this step.
On the Test menu, click Step Into. Developer opens the child flow service and selects
(but does not execute) the first step.
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.
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.
311
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.
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 311 or To
trace to a specified point on page 309 if you need procedures for this step.
On the Test menu, click Step Into. Developer selects on the Pipeline tab (but does not
execute) the first transformer in the MAP step.
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.
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:
312
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
Services Use of Cache on page 146.
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.
In the editor, select the step that will function as the breakpoint. (During debugging,
processing will halt immediately before this step).
On the Test menu, click Set Breakpoint. The steps icon turns red, indicating that it is a
breakpoint.
313
On the Test menu, click Clear Breakpoint. The steps icon returns to its normal color,
indicating that it is no longer a breakpoint.
OR
On the Test menu, click Breakpoints to display the current list of breakpoints on the
current server.
Click Remove.
In the editor, select the MAP step containing the transformer that will function as the
breakpoint.
On the Pipeline tab, select the transformer that will function as the breakpoint. (During
debugging, processing will halt immediately before this transformer.)
In the editor, select the MAP step that contains the transformer from which you want
to clear a breakpoint.
314
On the Pipeline tab, select the transformer from which you want to clear a breakpoint.
OR
1
On the Test menu, click Breakpoints to display the current list of breakpoints on the
current server.
Click Remove.
315
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.
316
On the Compose menu, click Disable Step. The step dims, indicating that it is disabled.
To enable a step in a flow service
In the editor, select the disabled step that you want to re-enable.
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.
Disabled transformers are not executed at run time
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.
317
In the editor, select the MAP step containing the transformer that you want to disable.
In the editor, select the MAP step containing the disabled transformer that you want
to enable.
On the Pipeline tab, select the disabled transformer that you want to enable.
In the editor, select the INVOKE or MAP step that contains the link with the condition
you want to disable.
On the Pipeline tab, select the link with the condition that you want to disable.
In the General category of the Properties panel, set the Evaluate copy condition property
to False.
318
In the editor, select the INVOKE or MAP step containing the link with the condition
you want to enable.
On the Pipeline tab, select the link with the condition that you want to enable.
In the General category of the Properties panel, set the Evaluate copy condition property
to True.
319
Use the Step, Step Into, or Trace to Here command to load values into the pipeline for the
current step.
In the Results panel, select the name of the variable for which you want to change the
value.
In the Modify Value dialog box, type the new pipeline value for the variable.
To debug the rest of the service with the new pipeline value, use the Step, Step Into, or
Trace to Here command. Keep in mind that the value is only changed for the current
debugging session; it is not changed permanently.
To drop values from the current pipeline
Use the Step, Step Into, or Trace to Here command to load values into the pipeline for the
current step.
In the Results panel, select the name of the variable that you want to drop from the
pipeline.
Right-click and select Drop. The variable disappears from the Results panel.
To debug the rest of the service with the dropped pipeline value, use the Step, Step
Into, or Trace to Here command. Keep in mind that the value is only dropped for the
current debugging session; it is not dropped permanently.
320
321
Select the directory in which you want the file saved and
assign a name to the file.
Save Pipeline to
Server
Specify the name of the file in which you want the pipeline
saved. By default, Developer saves the file to
IntegrationServer_directory\pipeline, which is where the
restorePipelineFromFile service expects pipeline files. If you
specify a relative path in the file name, the path is
understood to be relative to the pipeline directory.
322
Invoke pub.flow:savePipelineToFile at the point where you want to save a copy of the
pipeline.
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.
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.)
323
Display the Results panel. (If you simply want to inspect a saved pipeline, create a
new, empty flow service and display its Results panel.)
324
To...
Select...
Invoke pub.flow:restorePipelineFromFile at the point where you want to load the pipeline
file.
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
true
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.)
325
326
15:46:58
15:46:58
15:47:00
15:47:03
15:47:10
15:47:10
15:47:11
15:47:14
15:47:14
15:47:14
15:47:14
15:47:15
15:47:18
15:47:20
15:47:20
15:47:21
15:47:21
15:47:21
15:47:21
15:47:22
15:47:22
15:47:22
15:47:22
15:47:22
15:47:26
15:48:07
15:49:12
15:49:14
15:49:15
15:49:30
15:49:35
15:49:36
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
EDT
[ISS.0025.0001C]
[ISS.0025.0006C]
[ISS.0025.0017C]
[ISS.0025.0024C]
[ISS.0025.0023C]
[ISS.0025.0021C]
[ISS.0025.0008C]
[ISS.0025.0010C]
[ISS.0025.0020C]
[ISS.0025.0022C]
[ISS.0025.0018C]
[ISS.0025.0012C]
[ISS.0098.0026D]
[ISS.0098.0026D]
[ISS.0098.0021D]
[ISS.0106.0003D]
[ISS.0106.0005D]
[ISS.0106.0001D]
[ISS.0025.0032C]
[ISS.0100.0001C]
[ISS.0025.0004C]
[ISS.0025.0002C]
[ISS.0025.0011C]
[ISS.0028.0001C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
[ISS.0028.0005C]
(under Windows)
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 Audit 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 webMethods
Administering Integration Server.
327
16:56:12
16:56:53
16:57:56
16:57:56
EDT
EDT
EDT
EDT
[ISS.0028.0005C]
[ISC.0081.0001E]
[ISP.0090.0004C]
[ISP.0090.0004C]
Invoke pub.flow:debugLog at the point where you want the service to write a message to
the server log.
328
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.
Key
Description
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 services 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
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.)
For additional information about pub.flow:debugLog, see the webMethods Integration Server
Built-In Services Reference.
329
Invoke pub.flow:tracePipeline at the point where you want the service to dump a copy of
the pipeline to the server log.
Description
level
Optional. A String specifying the debug levels under which the pipeline
will be posted to the log. If the server is running at a debug level lower
than the value set in level, the pipeline is not written to the log file.
If you do not specify level, Fatal is assumed, which means that the
pipeline 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 327.
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.)
Execute the service. For additional information about pub.flow:tracePipeline, see the
webMethods Integration Server Built-In Services Reference.
330
12
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
332
334
334
335
341
347
352
352
331
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;
}
332
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.
333
334
Stage 2
Stage 3
Specify the inputs and outputs of the service. This stage is optional, but
recommended. During this stage, you define the services inputs and
outputs (if you know these) in Developers IDE. For information about
this stage, see Generating Java Code from Service Input and Output
Parameters on page 339.
Create the Java service using Developer. During this stage, you write your
program in Developers IDE. For information about this stage, see
Creating a Java Service with Developers IDE on page 338.
Specify the services run-time parameters. During this stage, you assign
parameters that configure the run-time environment for this service. For
information about this stage, see Setting Run-Time Options for a Java
Service on page 341.
335
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.
336
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.
337
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.
In the New Java Service dialog box, next to Folder, select the folder into which you
want to save this service.
Click Finish.
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 339.
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.
If you want to make additional methods and/or structures available to the service,
complete the following fields on the Shared tab.
338
To specify...
Extends
To specify...
Implements
The names of Java packages that this class imports. Take the
following steps to specify each package that you want to import:
Click
Data structures, methods, and other Java code that you want to
make available to all services in this folder.
When you finish specifying your code in the Java service editor and on the Shared tab,
click
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.
Add the location of the Java compiler to the system path of the machine where the
Integration Server is installed.
Variable Name
Type
State
String
339
Output
Amount
String
Variable Name
Type
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.
To generate Java code from the service input/output parameters
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).
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 141.
If you want to generate code for a subset of the variables on the Input/Output tab, select
those variables.
On the Code Generation dialog box, select For implementing this service and click Next.
340
Specify...
Specification
Whether you want to generate code for the input variables, the
output variables, or both.
Which fields?
341
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.
342
Stage 2
343
Stage 3
Stage 4
Stage 5
Create the Java service using your IDE. During this stage, you write and
compile your program in your IDE. For more information about this
stage, see Writing the Source Code for a Service on page 343.
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 344.
Publish the service to the webMethods Integration Server. During this stage, you
register your service on the Integration Server using the jcode utility. For
information, see Using the jcode Utility on page 345.
<<IS-START-IMPORTS>> --com.wm.data.*;
java.util.*;
<<IS-END-IMPORTS>> ---
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 21, jcode tags. For
additional information about the jcode utility, see the next section Using the jcode
Utility.
344
345
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 want the jcode utility to run using a different compiler, specify the compiler you
want to use in the jcode.bat file. Set the watt.server.compile system property on the line
with the Java command. The property must have the following format:
"-Dwatt.server.compile="path_to_your_java_compile -classpath {0} -d {1} {2}"
For example:
-Dwatt.server.compile="C:\java\jdk1.6.0_11\bin\javac -classpath {0} -d {1}
{2}"
Using this example, the Java command would be changed to the following:
"%JAVA_DIR%\bin\java" -Dwatt.server.compile="C:\java\jdk1.6.0_11\bin\javac classpath {0} -d {1} {2}" -classpath
"%IS_DIR%\..\common\lib\ext\mail.jar;%IS_DIR%\..\common\lib\ext\enttoolkit.j
ar;%IS_DIR%\..\common\lib\wmg11nutils.jar;%IS_DIR%\..\common\lib\ext\icu4j.jar;%IS_DIR%\..\common\lib\wm
-isclient.jar;%IS_DIR%\lib\wm-isserver.jar" com.wm.app.b2b.server.NodeUtil
"%IS_DIR%" %1 %2 %3 %4 %5
The watt.server.compile property specifies the compiler command that you want
Integration Server to use to compile Java services. For more information about this
property, see the webMethods Administering Integration Server.
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:
346
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
347
Make sure you have a C/C++ compiler installed on the host where webMethods
Integration Server in installed.
Make sure that you have completed the procedures specified in
IntegrationServer_directory/sdk/c/README and/or
IntegrationServer_directory/sdk/cpp/doc/README to build the platform support
libraries needed by Integration Server and Developer.
Make sure the package in which you want to create the service already exists. If the package
does not already exist, create it using webMethods Developer. For more information
about creating a package, see Creating a Package on page 78. (If you do not have
Developer or Administrator privileges, ask your server administrator to do this.)
Make sure the directory for this package contains a code/libs directory. When you compile
your C/C++ service, the make file places the compiled service (a DLL) in this
directory. If the package does not already have a code/libs directory, create one before
you begin building the service.
Make sure the folder in which you want to create the service already exists. If the folder does
not exist, use Developer to create it. For details, see Creating New Elements on
page 47.
Declare the input and output parameters for your service in a specification. When Developer
generates the starter code for your service, it creates code that extracts the specified
input values from the pipeline and assigns them to variables in your program. It also
inserts your services output variables into the pipeline. To do this, Developer must
know the input and output requirements of your service. You supply this information
in a specification. For information about creating a specification, see Chapter 9,
Creating IS Schemas, IS Document Types, and Specifications.
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_directory\lib
-OR Copy the wmJNI.dll and wmJNIc.dll files located in
IntegrationServer_directory\lib to the IntegrationServer_directory directory
348
In the New C Service dialog box, in the list next to Folder, select the folder into which
you want to save this service.
In the Name field, type a name for the service and click Next.
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.
Click Finish.
349
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.
350
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 make file to customize it for your development environment. Set the
following path settings:
Set...
To...
JDKDIR
SEVRDIR
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 348.
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
351
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.
352
Description
progid
OR
guid
The Globally Unique Identifier (GUID) of the object that you want to
invoke.
context
server
DCOM only. The TCP/IP domain name of the machine where the DCOM
object is located. For example, doc.rubicon.com or 128.111.222.001.
user
Optional. DCOM only. The name of the user in which to launch the
remote COM object.
password
domain
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.
353
Description
pDispatch
dispName
The name of the COM method or property that you want to invoke.
accessType
params
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.
354
13
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
356
356
358
360
363
365
370
355
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.
By default, Integration Server writes a response message to an HTTP client using the
same content type that was included in the request message. However, you can specify
that your service send the response message using a different format. For example, if
your service receives a request that specifies text/xml as the content type, you can send a
response message that specifies text/html for the content type. To change the content-type
of the response message, code your service to call the pub.flow:setResponseHeader service
before it writes output to the pipeline.
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.
356
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:
To generate Java client code that invokes a service
1
Open the service for which you want to generate client code.
In the Code Generation dialog box, select For calling this service from a client, and then
click Next.
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.
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 sites 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.
357
File Name
Description
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
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 Software AG_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.
358
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:
To generate C/C++ client code that invokes a service
1
Open the service for which you want to generate client code.
In the Code Generation dialog box, select For calling this service from a client; then click
Next.
In the Language field, select the C/C++ platform for which you are creating client code.
Click Next.
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.
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 sites 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.
Description
CReadme.txt
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.
359
File Name
Description
ServiceName.c
Assumptions
webMethods Integration Server is running.
Visual Basic Version 6 is installed.
webMethods Type Library is installed.
Note: The webMethods Type Library is a COM object that Visual Basic uses to interact
with webMethods Integration Server. The webMethods Type Library is automatically
installed when you install Developer.
Environment Setup
Your system PATH environment variable must include the following directory:
Software AG_directory\jvm\win150\jre\bin\client
-ORSoftware AG_directory\jvm\win160\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.
360
Procedure
Use the following procedure to have Developer generate Visual Basic client code that
invokes a service.
To generate Visual Basic client code that invokes a service
1
Open the service for which you want to generate client code.
In the Code Generation dialog box, select For calling this service from a client, and click
Next.
In the Language field, select Visual Basic 5/6, and click Next.
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.
Click Finish.
Developer generates several files, including the serviceNameReadMe.txt file. This file
contains detailed information about all the generated files. Refer to it to complete
your client application and for information about deploying your client application.
General Files
File Name
Description
ServiceName.vbp
ServiceNameReadme.txt
361
Description
frmArrayInput.frm
frmOutput.frm
frmSetup.frm
frmStringInput.frm
frmTableInput.frm
wmSampleLib.bas
Description
ServiceName.bas
ServiceName.cls
File Containing the Code that Interacts with webMethods Integration Server
File Name
Description
wmVBConnection.bas
362
Assumptions
webMethods Integration Server is running.
Excel 97 or Excel 2000 is installed.
webMethods Type Library is installed.
Note: The webMethods Type Library is a COM object that Visual Basic uses to interact
with webMethods Integration Server. The webMethods 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.
To generate Excel client code that invokes a service
1
Open the service for which you want to generate client code.
In the Code Generation dialog box, select For calling this service from a client, and click
Next.
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.
363
Click Finish.
Developer generates several files, including the serviceNameReadMe.txt file. This file
contains detailed information about all generated files.
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.
Open the wmXLTemplate.xls file. When prompted to indicate whether you want to
enable macros, select Enable Macros.
Description
ServiceNameReadMe.txt
ServiceName.bas
ServiceName.cls
The service object. You include this object into your own
project.
364
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.
365
http://IS_server:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1
Item
Description
Identifies the webMethods Integration Server on which the service you want
to invoke resides.
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.
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.
366
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 users 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 367.
Key
Value
Data Type
sku
A1
String
skuList
A1
String list
quantity
String
quantityList
String list
367
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 Integration Server receives multiple input values that are associated with the same
variable name, the String variable in the IData object will contain only the value of the
first variable. The String list variable will contain all the values. For example, the
following shows a URL that contains two values for the variable year and the resulting
IData object that Integration Server creates:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999
Key
Value
Data Type
year
1998
String
yearList
1998
String list
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 Integration
Server will contain three values for the variable named Color. The following shows the
IData object that the server passes to the service:
Key
Value
Data Type
Color
blue
String
ColorList
blue
String list
green
red
368
Value
Data Type
year
1998
String
yearList
1998
String list
1999
month
June
String
To instruct Integration Server to create a List of all input variables, set the parameter to
always. For example, for this request:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999&month=June
Value
Data Type
year
1998
String
yearList
1998
String list
1999
month
June
String
monthList
June
String list
To instruct Integration Server to ignore duplicates of the same variable, set this parameter
to never. For example, for this request:
/invoke/sample.webPageDemo/checkYears?year=1998&year=1999&month=June
369
Value
Data Type
year
1998
String
month
June
String
370
14
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
372
372
373
376
379
382
371
Overview
You can submit XML documents to the webMethods Integration Server from a client,
and have the Integration Server receive XML documents with services that you write. The
Integration Server provides the following automated mechanisms for receiving arbitrary
XML documents, parsing them or directly passing them as input to a specified service.
A client submits an XML document to a service in a String variable (of any name),
which the target service converts into a node using pub.xml:xmlStringToXMLNode.
A client submits an XML document to a service in a special String variable named
$xmldata, and webMethods Integration Server automatically parses the variable and
passes it to the service as a node.
A client posts an XML document to a service via HTTP, and Integration Server parses
the XML and passes it to the service as a node or directly passes it to the service as a
stream or byte without parsing.
A client FTPs an XML document to a service.
A client e-mails an XML document to a service.
A client sends the XML document as an e-mail attachment.
Puts the String into the element orders in an IData object named inputs
372
import
import
import
import
public
com.wm.app.b2b.client.*;
com.wm.util.*;
com.wm.data.*;
java.io.*;
class ArbitraryXMLClient
.
.
.
//--Load XML into orders string
String orders = YourLoadXMLMethod(orderFile);
//--Put input values into IData object
IData inputs = IDataFactory.create();
IDataCursor inputsCursor = inputs.getCursor();
inputsCursor.insertAfter("orders", orders);
inputsCursor.insertAfter("authCode", authCode);
373
com.wm.app.b2b.client.*;
com.wm.util.*;
com.wm.data.*;
java.io.*;
The service invoked by this client must be a service that takes a node as an input variable
(for example, queryXMLNode, xmlNodeToDocument), because this is what webMethods
Integration Server produces when it receives this request.
Important! This example shows a Java-based client; however, any type of IS client (even
a browser-based client) can be used. With a browser-based client, you would post the
XML document as the value portion of a $xmldata=value pair. You may post other
name=value pairs with the request.
374
To ...
url
The URL of the service that you want to invoke. The following value
would invoke the purch:postOrder service from a server named
rubicon with port number 5555.
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=stream
xmlFormat=stream directs the Integration Server to pass XML as a
stream directly to the requested service without parsing.
When this parameter is set to stream, the XML appears in the input
pipeline of the service as an InputStream named xmlStream.
375
To ...
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=bytes
get
headers.Content
-Type
text/xml
data.args
Name
Value
$xmldata
376
Client Requirements
Since most browsers do not allow you to modify the Content-Type header field, they are
not suitable clients for this type of submission. Clients that you might use to submit an
XML document in this manner are PERL scripts (which allows you to build and issue
HTTP requests) or the webMethods Integration Server service, pub.client:http.
Regardless of which client you use, it must do the following:
Submit a POST request to webMethods Integration Server.
Address the request to the URL of a service (for example,
http://rubicon:5555/invoke/purch/postOrder ).
Set the Content-Type header field to text/xml.
Contain an XML document in the body of the message. The document must be the
only text that appears in the body of the request. Do not assign it to a name=value
pair.
Important! When you submit the XML document, place an extra carriage return/new
line (\r\n) at the end of it to indicate the end of the XML document.
To...
url
The URL of the service that you want to invoke. The following
value would invoke the purch:postOrder service from a server
named rubicon with port number 5555.
Example http://rubicon:5555/invoke/purch/postOrder
method
post
headers.Content-Type
text/xml
data.string
OR
data.bytes
You will also set any optional HTTP parameters, such as authorization information, that
are required by your application.
377
To ...
url
The URL of the service that you want to invoke. The following
value would invoke the purch:postOrder service from a server
named rubicon with port number 5555.
Example
http://rubicon:5555/invoke/purch/postOrder?xmlFormat=stre
am
xmlFormat=stream directs the Integration Server to pass XML as
a stream directly to the requested service without parsing.
378
To ...
method
post
headers.Content-Type
text/xml
data.string
OR
data.bytes
A file extension whose mime type is registered with the server as text/xml.
To do this, edit the Integration Servers lib/mime.types file. For example:
text/xml
mimetype
No file extension
To configure a content handler to handle files that have no extension, use the
special key ftp_no_extension in the lib/mime.types file to indicate a null
extension. Then, specify the content type mapped to a null extension. For
example, the following XML content handler is used to handle files without an
extension:
text/xml
ftp_no_extension
379
If you want to use a different key to specify a null extension, use the property
watt.net.ftp.noExtensionKey to specify the key used in lib/mime.types to
specify a file with no extension. The default value of this property is
ftp_no_extension.
The service to which you want to pass the document must take a node as input.
Client Requirements
If you want to submit an XML document to a service through FTP, the application
sending the document must do the following:
1
Point to the directory that contains the service to which you want to pass the XML
document.
Example cd \ns\Purchasing\SubmitOrder
Important! Note that the root directory for this operation is your webMethods
Integration Servers namespace directory (ns), not the root directory of the target
machine. Therefore, if you want to FTP a file to a service in the Purchasing package,
you use \ns\Purchasing\ServiceName as the path to that service, not
IntegrationServer_directory\ns\Purchasing\ServiceName.
Copy the XML document to this directory using the following command:
put XMLDoc.xml
or
put XMLDoc
Where XMLDoc is the name of the file that you want to pass to webMethods
Integration Server. The file extension can be something other than xml if the
extensions mime type is registered with the server as text/xml. Alternatively, the file
extension can be omitted if you specify the special key ftp_no_extension in the
lib/mime.types file to indicate a null extension. See Submitting and Receiving XML
via FTP on page 379 for details.
Example put PurchaseOrder.xml
Note that the XML document you FTP to webMethods Integration Server is never
actually written to the servers file system. The XML document you send and the
output file it produces (see below), are written to a virtual directory system
maintained in your IS session.
380
Where XMLDoc.xml is the name of the XML file initially FTPed to the service. (The file
extension can be something other than xml if the extensions mime type is registered
with the server as text/xml.)
You retrieve this XML document using the FTP get command. For example, if you put
an XML document called PurchaseOrder.xml on webMethods Integration Server, you would
use the following FTP command to get its results:
Example get PurchaseOrder.xml.out
Important! We recommend that you use a unique name for each XML document that
you FTP to webMethods Integration Server (perhaps by attaching a timestamp to the
name) so that you do not inadvertently overwrite other FTPed XML documents or
their results during an FTP session.
When you end the FTP session, webMethods Integration Server automatically deletes the
original file and its results from your session.
381
Client Requirements
To submit an XML document to webMethods Integration Server via e-mail, your client
program must:
Put the XML document in an e-mail attachment.
Set the e-mails Content-Type header to text/xml.
Specify the name of the service that will process the XML document in the e-mails
subject line. If you leave the subject line empty, the XML document will be processed
by the global service if one is defined or, if not, by the default service assigned to the
e-mail port (if one has been assigned). For information about specifying the ports
default service, see webMethods Administering Integration Server.
The service that processes the XML document must take a node as input.
To...
to
subject
382
To...
from
body
attachments.contenttype
attachments.content
OR
attachments.filename
383
384
15
Subscribing to Events
386
389
396
398
399
385
15 Subscribing to Events
Description
Alarm
Audit
Error
Exception
Guaranteed
Delivery
JMS Delivery
Failure
Occurs when the contents of a JMS message sent from the client side
queue cause the JMS provider to throw a non-transient error.
Subscribe to JMS delivery failure events to capture information
about JMS messages that the JMS provider did not process
successfully. For example, you might want to use the event handler
to send notification or log information about the undelivered JMS
message.
386
15 Subscribing to Events
Event Type
Description
JMS Retrieval
Failure
Journal
Port Status
Replication
Security
Session
387
15 Subscribing to Events
Event Type
Description
Stat events
Transaction
events
388
15 Subscribing to Events
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 Event Manager in Developer to subscribe to events
To subscribe to an event, specify the
type of event that you want to react to...
...a filter to select the specific events you
want to react to...
...and the name of the event handler that
is to be executed when this event occurs.
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
389
15 Subscribing to Events
In the Event Manager dialog box, in the View event subscribers for list, select the event
type to which you want to subscribe.
Click
In the Enter Input Values dialog box, complete the following fields:
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 391.
Comment
Enabled
390
15 Subscribing to Events
Alarm Event
Audit Event
The fully qualified name of the service that generates the audit
event. Create a filter to specify the services whose audit events
you want to invoke the event handler.
The following filter specifies that the service
sgxorders.Authorization:creditAuth will invoke the event handler:
sgxorders.Authorization:creditAuth
Error Event
The error message text. The following filter specifies that any error
event with a message that contains the word "missing" will invoke
the event handler.
*missing*
Exception Event
391
15 Subscribing to Events
GD End Event
N/A
The filter for all GD End events is the following:
*
GD Start Event
The fully qualified name of the service that is being invoked using
guaranteed delivery. Create a filter to specify the services that,
when invoked using guaranteed delivery, will invoke the event
handler.
The following pattern string specifies that all services that start
with the word sendPO and belong to any folder will invoke the
event handler:
*:sendPO*
JMS Delivery
Failure Event
The name of the JMS connection alias used to send the message to
the JMS provider.
The following filter specifies that a JMS delivery failure event
involving a JMS connection alias with XA in the JMS connection
alias name will invoke the event handler:
*XA*
JMS Retrieval
Failure Event
The fully qualified name of the JMS trigger that called the trigger
service for which the error occurred.
The following filter specifies that a JMS retrieval failure event
involving a JMS trigger named ordering:processTransaction will
invoke the event handler:
*ordering:processTransaction*
Journal Event
The major code and minor code of the generated event. The
format of the filter is <majorCode>.<minorCode>. For example, the
following filter specifies that any journal event with major code of
28 followed by a minor code of 34 will invoke the event handler:
*28.34*
N/A
The filter for all port status events is the following:
*
Replication Event
392
15 Subscribing to Events
Security Event
N/A
The filter for all session end events is the following:
*
N/A
The filter for all session end events is the following:
*
Session Expire
Event
N/A
The filter for all session expire events is the following:
*
The user name for the user starting the session on the Integration
Server or the groups to which the user belongs. Create a filter to
specify which users or which user groups invoke an event handler
when they start a session on the server.
The following filter specifies that a session start event generated
by a user in the Administrators group will invoke the event
handler.
*Administrators*
Stat Event
N/A
The filter for all stat events is the following:
*
Tx End Event
N/A
The filter for all Tx End events is the following:
*
Tx Start Event
N/A
The filter for all Tx Start events is the following:
*
393
15 Subscribing to Events
sgxorders.Auth:creditAuth
sgxorders.Auth:credit*
sgxorders.Auth:*
sgxorders.*
*.Auth*:credit*
*:credit*
All services.
In the View event subscribers for list, select the event type for which you want to view
subscriptions.
Modify the fields in the Enter Input Values dialog box as needed and then click OK.
Click OK when you finish viewing or editing event subscriptions. Your changes take
effect immediately.
394
15 Subscribing to Events
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.
In the Enter Input Values dialog box, in the Enabled list, select false.
Click OK when you finish suspending event subscriptions. Your changes take effect
immediately.
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.
Click OK when you finish deleting subscriptions. Your changes take effect
immediately.
395
15 Subscribing to Events
Creating an empty service. During this stage, you create the empty service that
you want to use as an event handler.
Stage 2
Declaring the input and output. During this stage, you declare the input and
output parameters for the event handler by selecting the specification or IS
document type for the event type in pub.event. The specification and IS
document type indicate the run-time data that will be contained in the IData
object passed to the event handler.
Stage 3
Inserting logic, code, or services. During this stage, you insert the logic, code, or
services to perform the action you want the event handler to take when the
event occurs. If you are building a flow service, make sure to link data
between services and the pipeline.
Stage 4
Testing and debugging the service. During this stage, you use the testing and
debugging tools available in Developer to make sure the event handler
works properly.
Stage 5
Subscribing to the event. During this stage, you use the Event Manager to
subscribe the event handler to the event. This action registers the event
handler with the Event Manager and specifies which events will invoke it.
You can create filters to be more selective about which events you subscribe
to.
In the Select dialog box, navigate to and select the pub.event:sessionStart specification.
Click OK.
396
15 Subscribing to Events
Stage 3
In the Browse dialog box, navigate to and select the pub.client:smtp service. Click OK.
Specify
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
body
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
Stage 4
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.
Stage 5
In the Event Manager dialog box, in the View event subscribers for list, select Session
Start Event.
Click
397
15 Subscribing to Events
In the Enter Input Values dialog box, complete the following fields:
In this field
Do this
Service
Click
and use the Select dialog box to navigate to and select the
processLogon service.
Filter
Type: *Administrators*
This pattern string specifies that the processLogon event handler will
execute only when a user belonging to a user group containing the
string Administrators logs on to the server.
Comment
Enabled
398
15 Subscribing to Events
399
15 Subscribing to Events
400
15 Subscribing to Events
A Guaranteed Delivery Transaction generates Guaranteed Delivery Events and Transaction Events
webMethods Integration Server
(remote)
2
Service B
Service A
Stage
Description
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.
The remote Integration Server sends the results of Service B to the requesting
client (here, the local Integration Server).
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 Developers Guide.
401
15 Subscribing to Events
402
15 Subscribing to Events
403
15 Subscribing to Events
404
15 Subscribing to Events
405
15 Subscribing to Events
406
16
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
408
408
409
407
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.
408
409
Insert a SEQUENCE step. This SEQUENCE step will act as the outer sequence for the try
sequence and the catch sequence.
Set this outer SEQUENCE to exit on SUCCESS. This indicates that the sequence will
exit when any child step in the sequence succeeds. If the inner try sequence (the first
child of this parent SEQUENCE) succeeds, then the inner catch sequence will be
skipped, an ISRuntimeException will not be thrown, and the entire service will have
executed successfully.
Insert an inner SEQUENCE step for the try sequence. This sequence will contain the logic
that you want the service to perform.
Set this inner try sequence to exit on FAILURE. This indicates that the try sequence
will exit when a step in the SEQUENCE fails. The Integration Server will then execute
the next step in the flow service, which is the catch sequence.
Make sure that the try sequence is a child of the outer sequence that you inserted in
step 1.
Insert the logic that you want the service to perform. These steps contain the work that you
want the service to do.
Make sure to indent the steps below/under the try SEQUENCE step.
Insert a SEQUENCE step for the catch sequence. This sequence contains the steps needed
to catch the exception, determine its cause, and then determine whether the service
can be retried.
Set the catch sequence to exit when DONE. This indicates that the Integration Server
executes every step in the catch sequence, even if one of the steps fails.
Make sure that the catch sequence is a child of the outer sequence that you inserted in
step 1.
Invoke pub.flow:getLastError in the catch sequence to retrieve error information. This service
retrieves information about the last exception that occurred in the flow service. In this
case, the pub.flow:getLastError service retrieves information about the error that caused
the try sequence to fail.
Make sure to indent the pub.flow:getLastError invoke step below the catch SEQUENCE
step.
Using pub.flow:getLastError to catch the error information is optional.
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.
410
Determine whether the last error is a transient error that can be retried.
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.
8
411
Name
Description
wrappedException
message
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.
412
Description
Step 1
Create outer SEQUENCE that exits on SUCCESS. This step creates a sequence that
wraps the try sequence and the catch sequence. The sequence is set to exit on
success so that the outer sequence will exit when a child step executes
successfully. That is, setting the outer sequence to exit on success allows the
outer sequence to exit without executing the catch sequence when the try
sequence succeeds.
Step
Description
1.1
Create try SEQUENCE that exits on FAILURE. This step creates the try
sequence that contains all of the logic you want the service to execute.
This step is set to exit on failure so that the Integration Server will
execute the next step (the catch sequence) within the outer sequence.
Step
Description
1.1.1
Insert service logic. This step represents the logic that you want
the service to perform. In many services, the service logic
might consist of multiple services or flow steps.
If the try sequence executes successfully, the entire outer
sequence exits. The Integration Server skips the catch sequence
because the outer sequence exits upon the success of any child
step (in this case, the try sequence). The Integration Server
then executes the next step in the flow service (the BRANCH
on /isTransientError step).
If an error occurs while executing this step, the try sequence
exits (it is set to exit on FAILURE), and the Integration Server
executes the catch sequence.
1.2
Create catch SEQUENCE that exits on DONE. This step creates the catch
sequence that contains the logic that should be performed when an
error occurs during the try sequence. This step contains logic that
evaluates the error to determine whether the entire service can be
retried.
The catch sequence is set to exit on DONE. This means that the
Integration Server executes all the steps in the catch sequence. The
Integration Server considers the catch sequence to be successful after all
the child steps execute. Because the catch sequence is successful, the
outer sequence exits (it is set to exit on SUCCESS), and the Integration
Server executes the next step in the flow service.
To determine whether a transient error occurred, this step contains the
following steps.
413
Description
Step
Description
1.2.1
1.2.2
1.2.3
Set flag to indicate whether service should retry. This step sets the
transient error flag to indicate if a try sequence failed because
of a transient error. In this case, if a transient error occurred,
the transient error flag (the variable isTransientError) is set to
true.
After this step executes, the Integration Server exits the catch
sequence, exits the outer sequence, and then executes the next
step in the flow service (the BRANCH on /isTransientError
step).
Step 2
Check transient error flag. This step specifies that the value of the isTransientError
variable should be used to determine whether the service should throw an
ISRuntimeException.
If the try sequence executed successfully, the Integration Server falls through
to the end of the service because the value of the switch variable does not
match any of the target steps (if the try sequence succeeded, isTransientError is
null). In this case, the Integration Server considers the execution of the flow
service to be successful.
414
Step
Description
2.1
17
BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
416
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
419
INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
420
LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
422
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
424
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
425
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
428
415
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.
Name of the
switch field is
choice
416
Name1
Name2
NameN
$null
no label
$default
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.
BRANCH step using expressions
if the expression of first child is true
if the expression of second child is true
Evaluate
labels is set to
true
if the expression of nth child is true
Otherwise
Child1
Child2
ChildN
$default
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.
Simple BRANCH step using expressions
417
Properties
The BRANCH step has the following properties.
Property
Description
Comments
Scope
Timeout
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
labels
Specifies whether or not you want the server to evaluate labels of child
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.
418
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
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
$loop
$flow
Entire flow.
label
419
Property
Description
Signal
Failure
message
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
Scope
420
Property
Description
Timeout
Label
Service
Validate input
Validate output
421
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.
The LOOP step
No
input is
an array
more input
array
members?
Yes
get next
member of
input array
child
child
child
Properties
The LOOP step has the following properties.
Property
Description
Comments
Scope
422
Property
Description
Timeout
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.
423
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
Scope
Timeout
Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, Integration Server issues
a FlowTimeoutException and execution continues with the next step in the
service.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%. The
variable you specify must be a String.
If you do not need to specify a time-out period, leave Timeout blank.
For more information about how Integration Server handles flow step
timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter in
webMethods Administering Integration Server.
Label
424
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.
The REPEAT step
reps=0
child
child
child
reps = reps + 1
wait for
repeat
interval
Yes
Yes
Repeat
condition
met?
No
Exit
No
Exit
425
Properties
The REPEAT step has the following properties.
Property
Description
Comments
Scope
Timeout
Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, Integration Server
issues a FlowTimeoutException and execution continues with the next
step in the service.
If you want to use the value of a pipeline variable for this property, type
the variable name between % symbols. For example, %expiration%. The
variable you specify must be a String.
If you do not need to specify a time-out period, leave Timeout blank.
For more information about how Integration Server handles flow step
timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter in
webMethods Administering Integration Server.
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
426
Property
Description
Repeat
interval
Optional. Specifies the number of seconds the server waits before reexecuting 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%. The
variable you specify must be a String.
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
FAILURE
If the REPEAT step is a child of another step, the failure is propagated to its parent.
427
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.
The SEQUENCE step
If exit condition
is not met...
First...
child
child
If exit condition
is not met...
child
Properties
The SEQUENCE step has the following properties.
Property
Description
428
Property
Description
Timeout
Optional. Specifies the maximum number of seconds that this step should
run. If this time elapses before the step completes, Integration Server issues a
FlowTimeoutException and execution continues with the next step in the
service.
If you want to use the value of a pipeline variable for this property, type the
variable name between % symbols. For example, %expiration%. The variable
you specify must be a String.
If you do not need to specify a time-out period, leave Timeout blank.
For more information about how Integration Server handles flow step
timeouts, refer to the description of the
watt.server.threadKill.timeout.enabled configuration parameter in
webMethods Administering Integration Server.
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).
Exit on
To...
FAILURE
SUCCESS
DONE
429
430
18
Regular Expressions
432
432
433
431
18 Regular Expressions
retains the first 30 characters in each matching element and discards the rest.
432
18 Regular Expressions
To
433
18 Regular Expressions
Use this
symbol
( )
To
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.
{n }
{n ,}
{0,m }
{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.
434
18 Regular Expressions
Use this
symbol
To
\b
\B
\A
\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
\r
\t
435
18 Regular Expressions
Use this
symbol
To
\f
\d
\D
\w
\W
\s
436
18 Regular Expressions
Use this
symbol
To
\S
\0
\xnn
[ ]
To
437
18 Regular Expressions
438
19
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
440
444
439
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.
Data Type
Description
Java Type
String
String of characters.
java.lang.String
String list
A one-dimensional String
array.
java.lang.String[ ]
String table
A two-dimensional String
array.
java.lang.String[ ][ ]
Document
com.wm.data.IData
A one-dimensional array
of IS document types
(IData [ ]or Values [ ]).
com.wm.data.IData [ ]
Document list
Icon
com.wm.util.Values
For more information, see the
webMethods Integration Server
Java API Reference.
com.wm.util.Values [ ]
com.wm.util.Table
Document
reference
A document whose
structure is defined by an
IS document type.
Document
reference list
440
Data Type
Object
Object list
Icon
Description
Java Type
An array of Objects of
unknown type.
Example java.io.InputStream
Example java.io.InputStream[ ]
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 279.
modifier.
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.
441
The following table identifies the Java classes you can apply to Objects and Object list
variables in Developer.
Data Type
Description
Java Class
boolean
True or false.
java.lang.Boolean
boolean list
java.lang.Boolean[ ]
byte
java.lang.Byte
byte [ ]
primitive type
byte list
java.lang.Byte[ ]
character
java.lang.Character
character list
A one-dimensional character
array.
java.lang.Character[ ]
date
java.util.Date
date list
java.util.Date[ ]
double
java.lang.Double
double list
java.lang.Double[ ]
float
java.lang.Float
float list
java.lang.Float[ ]
integer
java.lang.Integer
integer list
java.lang.Integer[ ]
long
java.lang.Long
long list
java.lang.Long[ ]
442
Icon
Data Type
Icon
Description
Java Class
short
java.lang.Short
short list
java.lang.Short[ ]
XOPObject
com.wm.util.XOPObject
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 281.
443
To
Then
A scalar
variable
value
[empty]
value
If you link
To
Then
A scalar
variable
value
value
value
value
X
Y
Z
If you link
To
Then
An array
variable
A scalar variable
X
Y
Z
444
[empty]
If you link
To
Then
An array
variable
X
Y
Z
[empty]
X
Y
Z
If you link
To
Then
An array
variable
X
Y
Z
A
B
C
X
Y
Z
No link occurs.
V
W
X
Y
Z
A
B
C
445
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:
If you link...
To...
StringList1
DocumentList1
String1
DocumentList1
DocumentList1 [0]
String1
a
DocumentList1 [1]
a
b
c
String1 b
DocumentList1 [2]
String1
446
20
Conditional Expressions
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
448
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
449
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
453
Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
459
Addressing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
460
463
447
20 Conditional Expressions
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 180
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 225.
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 PublishSubscribe Developers 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 463.
448
20 Conditional Expressions
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.
Value Type
Syntax
Description
Regular
Expression
/regularExpression/
Variable
variableName
OR
%variableName%
Example
Explanation
sku = /^WM[0-9]+/
Explanation
price
%address/postalCode%
%poItems[0]%
449
20 Conditional Expressions
Value Type
Syntax
Description
String
"string"
OR
'string'
Example
Explanation
Favorite Customer
Favorite Customer
Null
450
number
$null
Explanation
-10, 5, 100
Integers
5.0, 6.02
6.345e+4
Scientific notation
Explanation
%quantity% = $null
20 Conditional Expressions
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
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
451
20 Conditional Expressions
Description
Variable
exists
variableName
Variable
does not
exist
452
!variableName
This example...
customerID
!quantity
20 Conditional Expressions
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 subscribers 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.
453
20 Conditional Expressions
If you use a standard relational operator to compare numbers in fields of type String,
Integration Server treats the contents in the field as numbers. To stop Integration
Server from treating the value as a number, you can put quotes (' or '') around the
variable name in the expression. For example %'var1'%=%'var2'%.
The following table identifies the standard relational operators you can use in
expressions and filters.
Operator
Syntax
Description
a=b
Equal to.
==
!=
<>
>
>=
454
a == b
a != b
a <> b
a>b
a >= b
This example...
customerID = "webMethods"
Equal to.
This example...
sku == "WM001"
quantity != 0
Greater than.
This example...
20 Conditional Expressions
Operator
Syntax
Description
companyID >= "Acme"
<
<=
a<b
a <= b
Less than.
This example...
quantity < 5
455
20 Conditional Expressions
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.
If you use a lexical operator to compare numbers in fields of type String, Integration
Server treats the numbers as strings.
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
L_NOT_EQUALS
L_LESS_THAN
L_LESS_OR_EQUAL
456
This example...
20 Conditional Expressions
Operator
Description
L_GREATER_THAN
L_GREATER_OR_EQUAL
This example...
Logical Operators
You can use the following logical operators in expressions to create conditions consisting
of more than one expression:
Operator
Syntax
Description
! expr
not
not expr
expr | expr
This example...
! (%sku% = "WM001")
%color% = "blue" |
%color% = "red"
457
20 Conditional Expressions
Operator
Syntax
Description
||
expr || expr
or
&
&&
458
expr or expr
expr &&
expr
This example...
creditCardNum = $null or
cardExpireDate = $null
or cardExpireDate <=
orderDate
%customerID% = 'Favorite
Customer' & %sku% =
'WM001'
20 Conditional Expressions
Operator
Syntax
Description
and
expr and
expr
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.
Precedence Level
Operators
()
not, !
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.
459
20 Conditional Expressions
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.
Use this notation
To
variableName
Address a variable.
Example: state
Variable state.
variableName/childVariableName
arrayVariableName[index]
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)
460
20 Conditional Expressions
To
%"variableWithSpecialCharacters"%
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 449.
461
20 Conditional Expressions
Following are some examples of how to address variables that contain special characters.
Type...
To...
%"Date/Time"%
%purchaseOrder/"Date/
Time"%
%"address(work)"/"phone
(cell)"%
%"Date\\Time"%
Character Name
Special sequence
backslash
\\
opening bracket
closing bracket
opening parenthesis
closing parenthesis
percent
\%
"
quotation marks
\"
462
20 Conditional Expressions
463
20 Conditional Expressions
Examples
No comparison operators
"fieldName"
"!fieldName"
%price% L_LESS_THAN 50
"stringName" > 12
myBoolean = "stringFieldName"
A $null token
%fieldName% = $null
fieldName = /^(a|b)\1$/
/a{1}/
fieldName = /\w/
464
/a{1,5}/
21
jcode tags
jcode Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
466
jcode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
467
465
21 jcode tags
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>> --// --- <<IS-END-IMPORTS>> --public class Interface0
{
public static void Service1 (IData pipeline)
throws ServiceException
{
// --- <<IS-START(Service1)>> --// --- <<IS-END>> --return;
}
public static void Service2 (IData pipeline)
throws ServiceException
{
// --- <<IS-START(Service2)>> --// --- <<IS-END>> --return;
}
// --- <<IS-START-SHARED>> --// --- <<IS-END-SHARED>> --}
466
21 jcode tags
jcode Example
The following is a complete example of properly commented Java source code.
Sample CodeIData
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)
467
21 jcode tags
*
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");
// Do something with the information here. Note that this
// comment inside the service body is the only one that won't
// get discarded when fragmenting the service (i.e., it will
// show up in Developer.)
idc.last();
idc.insertAfter ("message", "createAccount not fully implemented");
idc.insertAfter ("id", "00000000");
idc.destroy();
// --- <<IS-END>> --return;
}
/**
* == COMPLEX SIGNATURES ==
* The getAccount service. This service takes a single string
* "id", and returns a complex structure representing the
* account information. Note the use of the helper functions
* (defined below).
*/
public static void getAccount (IData pipeline)
throws ServiceException
{
// --- <<IS-START(getAccount)>> --// [i] field:0:required id
// [o] record:1:required account
// [o] - field:0:required name
// [o] - field:1:required refs
// [o] - record:0:required contact
// [o] -- field:0:required address
// [o] -- field:0:required phone
IDataCursor idc = pipeline.getCursor();
if(idc.first("id"))
{
try
{
String id = IDataUtil.getString(idc);
468
21 jcode tags
469
21 jcode tags
470
22
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
472
Content Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
473
Constraining Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
483
471
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).
472
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: For details about constraints for Objects and Object lists, see Appendix 19,
Supported Data Types.
Content Types
Description
anyURI
base64Binary
boolean
True or false.
Constraining Facets
pattern
Example
true, 1, false, 0
byte
473
Content Types
Description
date
dateTime
(August 9, 1997)
decimal
474
Content Types
Description
double
duration
ENTITIES
ENTITY
float
475
Content Types
Description
gDay
A specific day that recurs every month. Values must match the
following pattern:
---DD
Where 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
---24
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
gMonthDay
represents November
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
476
Content Types
Description
gYear
gYearMonth
indicates 2001
hexBinary
ID
477
Content Types
Description
IDREF
IDREFS
int
integer
language
478
Content Types
Description
long
Name
XML names that match the Name production of XML 1.0 (Second
Edition).
Constraining Facets
enumeration, length, maxLength, minLength, pattern, whiteSpace
NCName
negativeInteger
NMTOKEN
NMTOKENS
479
Content Types
Description
nonNegativeInteger
nonPositiveInteger
normalizedString
positiveInteger
short
480
Content Types
Description
string
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
token
unsignedByte
481
Content Types
Description
unsignedInt
unsignedLong
unsignedShort
482
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.
Constraining Facet
Description
Usage Notes
enumeration
fractionDigits
length
maxExclusive
maxInclusive
maxLength
483
Constraining Facet
Description
Usage Notes
minExclusive
minInclusive
minLength
pattern
totalDigits
whiteSpace
484
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.
485
486
23
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
488
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
488
Validation Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
502
507
487
Overview
This appendix describes the following:
Validation errors
Validation exceptions
Errors and warnings that may occur while generating 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.
Error Code
DT-001
DT-002
DT-003
488
Error Code
DT-004
DT-005
DT-006
DT-007
DT-008
DT-009
DT-010
DT-011
DT-012
489
Error Code
DT-013
DT-Binary001
DT-Binary002
DT-Binary003
DT-Binary004
DT-Boolean001
DT-Decimal001
DT-Decimal002
DT-Decimal003
490
Error Code
DT-Decimal004
DT-Decimal005
DT-Decimal006
DT-Double001
DT-Double002
DT-Double003
DT-Double004
DT-Float001
DT-Float002
491
Error Code
DT-Float003
DT-Float004
DT-Int001
DT-Int002
DT-Int003
DT-Int004
DT-INTEGER001
DT-INTEGER002
DT-INTEGER003
DT-INTEGER004
492
Error Code
DT-Long001
DT-Long002
DT-Long003
DT-Long004
DT-List001
DT-List002
DT-List003
DT-List004
DT-RecurringDuration001
493
Error Code
DT-RecurringDuration002
DT-RecurringDuration003
DT-RecurringDuration004
DT-STR001
DT-STR002
DT-STR003
DT-STR004
DT-Time001
DT-Time002
494
Error Code
DT-Time003
DT-Time004
DT-TimeDuration001
DT-TimeDuration002
DT-TimeDuration003
DT-TimeDuration004
DT-TimePeriod001
DT-TimePeriod002
DT-TimePeriod003
495
Error Code
DT-TimePeriod004
NV-001
NV-002
NV-003
NV-004
NV-005
496
Error Code
NV-006
NV-007
NV-008
NV-009
497
Error Code
NV-010
NV-011
NV-012
NV-013
498
Error Code
NV-014
NV-015
NV-016
NV-017
499
Error Code
NV-018
VV-001
VV-002
VV-003
500
Error Code
VV-004
501
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.
Default Exception Message
When is it thrown?
Description
[ISS.0062.9024] webMethods
Integration Server does not
support this type of validation
(may or may not support in
the future)
502
When is it thrown?
Description
Design time
[ISS.0062.9203] Invalid:
maxLength
Design time
[ISS.0062.9211] Invalid
Regular Expression:
Expression
[ISS.0062.9212] Invalid:
minInclusive
Design time
Design time
[ISS.0062.9213] Invalid:
minExclusive
Design time
503
When is it thrown?
Description
Design time
[ISS.0062.9215] Invalid:
maxExclusive
Design time
Design time
[ISS.0062.9231] Exceeds
precision: minInclusive
Design time
[ISS.0062.9232] Exceeds
precision: minExclusive
Design time
[ISS.0062.9233] Exceeds
precision: maxInclusive
Design time
504
When is it thrown?
Description
Design time
[ISS.0062.9235] Invalid
enumerated item
Design time
[ISS.0062.9302] Maximum is
less than minimum
Design time
505
[ISS.0062.9304] Maximum is
out of range (Valid range is
from lowerBound to
upperBound)
506
When is it thrown?
Description
Design time
Design time
DTDC-001
DTDC-002
DTDC-003
DTDC-005
507
Code
XSDC-001
XSDC-002
XSDC-003
XSDC-004
XSDC-005
XSDC-006
508
Code
XSDC-008
XSDC-009
XSDC-080
XSDC-081
509
Code
510
Index
Symbols
_env field 267
! 457
!= 454
" 462
( 462
) 462
/ 462
\ 462
& 458
&& 458
% 462
283
< 455
<= 455
<> 454
= 454
== 454
> 454
>= 454
| 457
|| 458
$xmldata 373
A
access control 118
ACLs
assigning to elements 118, 121
assigning to packages and folders 121
checking for services 119
defined 118
element creation, view, and deletion implications
126
inheritance 123
locking implications 125
requirements for using Developer 22
testing and debugging implications 125
viewing on a server 124
actions, performing on IS elements 36
adapter notifications
described 268
guidelines for moving and copying 55
adapter services, retry behavior 409
adding
folders 135
packages 78
transformers 235
variables to pipeline link 232
addressing
variables in expressions and filters 460
variables with special characters 461
alarm events
definition of 386, 399
reasons generated 399
uses of 399
all content model 249
Allow unspecified fields option 280
and operator 459
annotating source code for jcode 344
anonymous type definitions 249
any attribute declaration 248
any element declaration 248
anyURI content constraint 473
API for Java services 338
applying
conditions to links 225
constraints to variables 279, 472
areas of Developer window
behavior and operation 35
editor 31
focus 35
general layout 25
Navigation panel 26
Properties panel 33
Recent Elements tab 31
resizing 37
Results panel 35
switching perspectives 38
UDDI Registry tab 29
zooming 37
arithmetic services 235
array variables
default behavior for linking 444
definition of 444
guidelines for linking 224
linking to or from array variables 222, 444
511
Index
B
base64Binary content constraint 473
blank labels in BRANCH steps 184
blue links, in the Pipeline tab 223
booleans
content constraint 473
in filters, Broker restrictions 464
BRANCH step
branching on empty values 184
branching on expressions 183
branching on null values 184
branching on switch value 180
creating 188
creating a multi-step child for 186
definition of 132, 416
512
Index
invoking 178
throwExceptionForRetry 156
byte content constraint 473
C
C/C++ clients
creating 358, 359
creating a make file 359
C/C++ services
compiling with a make file 347
creating 347, 348
caching
definition of 146
elements to improve Developer performance 72
services not suited for 147
services suited for 147
setting 149
using prefetch 148
call stack 302
catch sequence, in service retry 409
changing
level of a step 175
passwords 41
position of a step 174
child flows
described 175
stepping in/out of child flows 311
tracing 309
choice content model 249
circular dependencies, between packages 89
class files
location of 342
clearing
breakpoints on flow steps 314
breakpoints on transformers 314
client applications
creating browser-based 365
creating C/C++ 358
creating Excel 363
creating Java 356
creating Visual Basic 360
closed documents, described 280
closing a session on webMethods Integration Server
39
coded services, about 332
collapsing
transformers 242
white space 484
COM objects
invoking as services 352
using with webMethods components 352
COM services
creating 352
com.wm.app.b2b.server.ISRuntimeException class
156
combining Trace and Step commands 307
commands
Disable Step 316, 317
Enable Step 316, 317
Load Pipeline Locally 324
Reset 307
Restore Pipeline from Server 324
Restore Pipeline Locally 324
Save Pipeline from Server 324
Save Pipeline Locally 322
Save Pipeline to Server 322
Set Breakpoint 313
Step 306, 310, 311
Step Into 306, 310, 311
Step Out 310, 311
Trace 306, 308
Trace Into 306, 308, 309
Trace to Here 306, 308, 309
comments for jcode 344
Comments property, definition 176, 420
compiling
C/C++ services 351
error in Java compiler location 339
Java services 339, 345
services with Developer 339
services with jcode 346, 347
specifying the Java compiler 339
complex type definition
all content model 249
anonymous 249
choice content model 249
described 249
empty content 249
expanding as inline IS document type 260
generating as separate IS document types 260
mixed content 249
recursive structures 260
sequence content model 249
composite mode (jcode) 347
conditional expressions
addressing variables 460
513
Index
514
context-sensitive menus 36
Control steps
BRANCH 132, 180
EXIT 132, 202
LOOP 132, 198
REPEAT 132, 190
SEQUENCE 132, 196
converting string lists to document (IData object) lists
221
copying
by reference, definition of 217
by value, definition of 217
elements from the Results panel 301
IS elements 53
pipeline values 230
set values 230
transformers 241
creating
code for Java services 339
event filters 391
event filters for services 394
event handler sample 396
event handlers 396
flow services 134, 135
folders 135, 348
IS elements 47
IS schemas 251
Java services with an IDE 343
Java services with C/C++ 347
Java services with Developer 335, 338
Java services with Visual Basic 352
Java services with your own IDE 341
links to array variables 444
links to document (IData object) variables 220
packages 78
specifications for C/C++ services 348
version numbers for packages 85
cursors 333
customizing content types 282
D
dagger symbol, next to variable icon 283
data transformations, definition of 208
data types
icons to represent 137
linking with Pipeline tab 220
supported by webMethods Integration Server 440
tables 443
Index
data validation
allowing undeclared variables 280
applying constraints 279
benefits of 278
blueprints for 278
closed variables 280
content constraints 279
definition of 278
document (IData object) validation 287
errors 488
exceptions 291, 502
input/output validation
definition of 284
performing via Input/Output tab 285
performing via INVOKE step properties 286
open variables 280
pipeline validation 288
requiring variable existence 280
structural constraints 279
types of 278
XML validation 288
date content constraint 474
date conversion services 235
dateTime content constraint 474
DCOM objects
invoking as services 352
using with webMethods Integration Server 352
debug level, setting on server 327
debugging flow services
breakpoints 313
combining trace and step 307
disabling a single flow step 316
disabling a transformer 317
disabling conditions on links 318
dumping the pipeline to serveryyyymmdd.log 329
enabling a single flow step 316
enabling a transformer 317
modifying the pipeline 319
overview 294, 305
resetting debug mode 307
stepping into a child flow 311
stepping into a transformer 312
stepping through a flow 306, 310
tracing a flow 306, 308
tracing into a child flow 309
using server debug facility 326, 327
debugLog service 328
decimal content constraint 474
declaring
input and output parameters 137
input for a service 138
output for a service 139
default value, assigning to a pipeline variable 228
defining packages 78
deleting
breakpoints on transformers 314
event subscriptions 395
IS elements 59
links between variables 225
packages 84
dependencies, package
identifying 88
removing 90
dependents
checking when renaming IS elements 49
confirming before deleting elements 49
finding service and document (IData object) 66
safeguards for updating 50
details perspective 38
Developer window, toolbar 30
Developer. See webMethods Developer
dimensionality, definition of 239
directories
Java services 341
Disable Step command 316, 317
disabling
a condition placed on a link 318
a flow step 316
a transformer 317
dispatch services
for COM 352
for DCOM 352
document (IData object) validation
definition of 287
errors 488
exceptions 502
performing 287
document data type 440
document list data type
converting from String list 221
definition of 440
document reference data type
creating 271
definition of 440
document reference list data type
creating 271
515
Index
definition of 440
Document Type Definitions. See DTDs
document types. See IS document types
documentation
accessing for packages 83
creating for packages 82
using effectively 17
documents (IData objects)
applying content constraints 472
assigning to a document or document list 256,
271
assigning to a specification 256
benefits of 256
creating 256
errors when creating from DTD or XML Schema
507
finding dependents 49
linking 220
open and closed 280
pipeline validation 288
printing 270
using as service parameters 256, 270
viewing in browser 270
double content constraint 475
DROP modifier 212, 231
dropping values from the pipeline 231
DTDs
creating documents (IData objects) from 256
creating IS document types from 258
creating IS schemas from 251
IS schema generation warnings 507
duration content constraint 475
E
edit perspective 38
editing
elements. See editor
event subscriptions 394
flow services 130
properties 34
Service property 177
simple types in IS schema 254
editor
described 31
help about 42
hiding and showing 37
inserting flow steps into 173
resizing 37
516
Index
permissions 118
references 67
renaming 57
saving 59
single-clicking does not open 51
unlocking 49
viewing as HTML 49
emailing XML to a service 382
empty
content 249
strings in filters 456
values, branching on 184
Enable service audtiting options, described 161
Enable Step command 316, 317
enabling
flow steps 316
service auditing 161
transformers 317
end-to-end linking 234
entering input for a service 296
ENTITIES content constraint 475
ENTITY content constraint 475
enumeration constraining facet 483
envelope field
in publishable document types 267
usage restrictions 267
error auditing, described 165
error events 386
error handling, in flow services 196
errors
data validation 488
document (IData object) generation 507
flow service generation 507
IS schema generation 507
pipeline validation 488
Evaluate labels property 189
event filters
creating 391
creating for services 394
event handlers
creating 396
creating sample 396
definition of 388
stages of creating 396
Event Manager
alarm events
definition of 386, 399
uses 399
audit events
definition of 386, 399
definition of 386
event behavior 388
event handlers 388
Event Manager command 389
exception events 386, 400
filters 391
GD End events 400
uses 400
GD Start events 400
uses 400
guaranteed delivery events 386
JMS delivery failure events 386, 392
JMS retrieval failure events 387, 392, 401, 402
pattern strings 391
port status events 387, 403
uses 403
replication events 387, 403
uses 403
run-time behavior 388
security events 387, 403
session end events 404
session events 387, 404
uses 404
session expire events 404
session start events 404
stat events 388, 405
uses 405
subscriptions
creating 389
creating filters for 391
deleting 395
editing 394
managing 389
suspending 395
viewing 394
transaction events 388, 405
Tx End events 405
uses 405
Tx Start events 405
uses 405
viewing subscriptions 395
events
See also event handlers, Event Manager
creating filters 391
creating filters for services 394
deleting subscriptions to 395
517
Index
F
facets, See constraining facets
failIfInvalid property 502
failure
of a flow step 196
of a REPEAT step 191
fields
content type constraint symbol 283
dagger symbol 283
green squares 283
optional symbol 283
filter collation locale 455
filtering events 391
518
filters
addressing variables 460
addressing variables with special characters 462
allowed quantifiers 464
back references 464
booleans in 464
braces {} in 464
checking for variable existence 464
collation locale, specifying 455
comparing strings and numeric values 464
comparison operators, missing 464
constrained Objects in 464
effect of locale 455
extended metacharacters 464
lexical relational operators 455
logical operators 457
$null 464
operators for 453
server performance 453
standard relational operators 453
syntax 449
syntax restrictions 463
variables with special characters 461
finding
elements in Navigation panel 62
invoked services 65
service and document (IData object) dependents
66
unresolved pipeline references 69
unresolved references 68
float content constraint 475
flow services
See also services, debugging flow services
breakpoints 313
caching to improve Developer performance 72
creating 135
debugging 305
definition of 130
disabling a single step 316
disabling a transformer 317
disabling conditions placed links 318
editing 130
enabling a single step 316
enabling a transformer 317
errors creating from DTD or XML Schema 507
inserting steps in a service 173
maximum retry period 155
printing 169
Index
G
GD End events
definition of 400
pub.remote.gd:end 400
uses of 400
when generated 400
GD Start events
definition of 400
pub.remote.gd:start 400
uses of 400
when generated 400
gDay content constraint 476
Generate Code command 357, 359, 361
generating complex types as document types 260
H
hailmary mode (jcode) 347
hard-coding input variables 227
help, obtaining 42
hexBinary content constraint 477
hiding and showing panels 37
HTML, viewing elements in 49
I
ID content constraint 477
IData objects
creating 333
519
Index
definition of 332
getting data from 333
positioning cursors 333
putting data in 333
using in a Java service 343
IDE
assigning a super class with 337
creating source code in 335
defining private methods with 338
implementing interfaces with 337
importing Java packages 337
in Developer 334, 335
using other IDEs 341
using the Java service editor 335
using the Shared tab 337
identifying
package dependencies 88
replication services 92
shutdown services 92
startup services 92
IDREF content constraint 478
IDREFS content constraint 478
implementing interface in Java services 337
implements (Java keyword) 337
implicit linking
described 213
for MAP steps 234
implicit universal names 158
import (Java keyword) 337, 343
import mechanism, in XML Schemas 253
importing Java packages 337, 343
include mechamism, in XML Schemas 253
index, array variables 223
Indexing tab. See linking array variables
Input array property 199
input variables
declaring for a service 137, 138
declaring in a document (IData object) 256
entering test values for 296
hard-coding 227
linking considerations 215
linking in the pipeline 214
loading values from a file 298
saving values to a file 298
input/output parameters
declaring for a service 137
generating Java code from 339
Input/Output tab 140
520
input/output validation
definition of 284
performing via Input/Output tab 285
performing via INVOKE step 286
inserting
INVOKE step 178
steps into flow services 173
transformers 235
installing Java services 341
int content constraint 478
integer content constraint 478
Integrated Development Environment. See IDE
Integration Server Administrator, unlocking elements
110
Integration Server. See webMethods Integration
Server
interfaces
implementing in Java service 337
INVOKE step
Comments property 420
creating 178
definition of 131, 420
finding 65
invoking built-in services 178
invoking services on another server 178
Label property 421
peforming validation via step properties 286
Pipeline tab 209
Scope property 420
Service property 177, 421
using in a flow 177
Validate input property 421
Validate output property 421
invoking
built-in services 178
remote services 178
services 178
services from a browser 366, 367
services on another server 178
IS document types
See also documents (IData objects)
creating empty document types 257
creating from Broker document type 265
creating from DTD 258
creating from XML document 258
creating from XML Schema 258
described 256
editing 269
Index
J
Java classes for object and object list variables 441
Java clients, creating 356, 357
Java keywords
extends 337
implements 337
import 337, 343
Java service editor 335
Java services
adding private methods to 338
compiler location 339
compiling with Developer 339
compiling with jcode 345
creating 338, 339
creating with an IDE 341, 343
creating with Developer 335
extending the class of 337
implementing interface in 337
importing packages into 337, 343
installing manually 341
jcode requirements 344
location of class files 342
location of source files 342
publishing to the server 341
required code 343
setting run-time options 341
K
keyboard shortcuts 36
L
L_EQUALS 456
L_GREATER_OR_EQUAL 457
L_GREATER_THAN 457
L_LESS_OR_EQUAL 456
L_LESS_THAN 456
L_NOT_EQUALS 456
Label property
definition 421
for evaluating expressions 183
for general use 176
for specifying the default BRANCH step 185
for targeting BRANCH steps 181
language content constraint 478
length constraining facet 483
lexical relational operators
conditional expressions 455
definition of 455
empty string 456
locale 455
non-string variables 456
libs directory 348, 351
link indices 223
linking
array variables 222
default rules 444
521
Index
522
M
make file
creating 347
using to compile C/C++ services 351
make mode (jcode) 346
MAP modifier
definition of 212
executing at run time 217
linking different data types 220
linking from service output 215
linking to service input 214
MAP step
debugging 312
definition of 131, 424
disabling transformers 317
enabling transformers 317
inserting transformers 235
Pipeline tab 211
transformers 234
using in a flow 205
using to initialize variables in a flow 205, 228
mapping. See linking
Max attempts property 157
maxExclusive constraining facet 483
maximum retry period, definition of 155
maximum retry period, description of 155
maxInclusive constraining facet 483
maxLength constraining facet 483
maxOccurs threshold value, for validation 292
memory
reducing usage 72
running out of during validation 292
menu bar, using to perform actions 36
metacharacters, in filters 464
methods, adding to a Java service 338
minExclusive constraining facet 484
Index
N
Name content constraint 479
name transformations, definition of 208
namespace information (for services)
creating source file from 347
location of 341
updating with jcode 346
namespaces
usage in universal names 157
XML namespace property 272
naming services 47
Navigation panel
described 26
help about 42
hiding and showing 37
icons 26, 103
refreshing contents of 29
resizing 37
toolbar 30
NCName content constraint 479
negativeInteger content constraint 479
NMTOKEN content constraint 479
NMTOKENS content constraint 479
nonNegativeInteger content constraint 480
nonPositiveInteger content constraint 480
not operator 457
notification, of server shutdown 41
ns directory 341
$null
in filters 464
in labels for BRANCH steps 184
null, branching on 184
O
Object data type
definition of 441
in filters 464
Object list data type, definition of 441
object list variables, Java classes 441
P
packages
adding 78
assigning version numbers 85
copying 81
creating 78
creating circular dependencies 89
cutting 81
definition of 76
deleting 84
dependencies, using with startup services 90
documenting 82
exporting 84
identifying dependencies 88
importing into Java services 337, 343
moving 81
naming guidelines 78
pasting 81
reloading 83
523
Index
reloading vs refreshing 83
removing dependencies 90
required by Java services 343
viewing details 79
viewing patch history 86
panels
editor 31
Navigation 26
Properties 33
Recent Elements 31
Results 35
switching perspectives 38
UDDI Registry 29
parameters
applying constraints 279
benefits of declaring 137
declaring 137, 141
declaring for a service 138, 139
parent/child relationships in a flow 175
passing XML to a service 372
passwords
changing 41
requirements 41
patch history
removal by Integration Server 87
viewing for a package 86
pattern constraining facet 484
pattern matching, in event subscriptions 391
Perform Variable Substitution option 229
Performance 164
performance impact, service auditing 164
permission
See also ACLs
assigning to elements 118
Permissions property 122
perspectives of views 38
pipeline
adding variables to 232
addressing variables 460
adjusting 212
assigning values to 227
changing values 319
checking for variables 452
conditional linking 225
copying values 230
definition of 132
DROP modifier 231
dropping values 319
524
Index
R
Recent Elements tab
described 29, 31
help about 42
hiding and showing 37
resizing 37
Record data type. See document data type
Record list data type. See document list data type
525
Index
526
REPEAT step
creating (on failure) 192
creating (on success) 194
definition of 132, 425
failure 191
specifying the repeat condition 190, 191, 427
using in a flow 190
using to retry a failed step 191
using to retry a successful step 194
replace white space 484
replication events
definition of 387, 403
uses of 403
replication services
assigning 92
definition of 91
guidelines for assigning 91
removing 93
when to use 91
requirements for passwords 41
requiring variable existence for validation 280
Reset command 307
resizing
panels 37
window areas 37
Restore Pipeline from Server command 324
Restore Pipeline Locally command 324
restorePipelineFromFile service 321, 324
restoring
pipeline values from a file
into Results panel 324
with restorePipelineFromFile service 325
sessions 40
Results panel
copying elements from 301
described 35
general information 300
help about 42
hiding and showing 37
resizing 37
saving results from 321
retried audit log status 155
Retry interval property 157
Retry on ISRuntimeException category 157
retry period, maximum 155
retry, for service 155
retrying a flow step 190
Run command 295
Index
S
Save Pipeline Locally command 322
Save Pipeline to Server command 322
savePipelineToFile service 323
saving
changes to elements 59
elements (IS) 59
input values to a file 298
test results using savePipelineToFile service 323
test results, overview 321
scalar variables
default behavior for linking 444
definition of 444
linking to or from array variables 444
scale constraining facet 483
schema browser, definition of 247
schema details area, definition of 250
schema domains 251
schema editor 246
schema processor, definition of 251
schema services
for document (IData object) validation 287
for pipeline validation 288
for XML validation 288
Scope property, definition 420
Send XML File command 305
sending XML documents
to a service 372
via email 382
via FTP 379
via HTTP 376
sequence content model 249
SEQUENCE step
as target for a BRANCH 186
definition of 132, 428
setting exit condition 196
using in a flow 196
server files, viewing for locked elements 112
server. See webMethods Integration Server
serveryyyymmdd.log file 327
contents of 327
dumping pipeline to 329
overview 326
service auditing
configuring 159
described 159
enabling 161
error auditing 165
failed and successful services 166
including pipeline 163
performance impact 162, 164
specifying which states to log 161
use cases 165
Service In 209
service log
configuring 159
described 160
Service Out 210
Service property
definition 421
definition of 177
editing 177
for transformers 236
renaming transformers with 243
service retry
adapter services 409
audit log 155
basic componenents 409
configuring 155
example 412
overview 408
requirements 156, 408
restrictions 156
throwing exceptions for 408
services
assigning universal names 157
audit data
enabling 161
when generated 161
auditing
configuring 159
enabling 161
for recovery 167
long-running services 167
options 167
caching to improve Developer performance 72
configuring retry 155
creating event filters for 394
creating flow 135
creating with Visual Basic 352
527
Index
528
Index
T
tables, support of 443
tabs
Input/Output tab 140
Pipeline tab 208
Schema tab. See schema editor 246
selecting 31
Settings tab for services. See also Properties
panel 341
Shared tab 337
tagging source code for jcode 344
templates
assigning to a service 142
definition of 142
test perspective 38
test results
changing pipeline values 319
copying 301
loading 321
saving 321
viewing 299
testing services
entering test input 296
from a browser 304
from Developer 295
inspecting the pipeline 299
loading input values from a file 298
loading the pipeline 321
overview 294
run-time exceptions 301
saving input to a file 298
saving the pipeline 321
setting breakpoints 313
testing in debug mode 305
viewing results 299
viewing the call stack 302
viewing the pipeline 303
XML document as input 305
threshold value, for maxOccurs 292
throw exception for retry 409
time content constraint 481
time conversion services 235
timeDuration content constraint 475
Timeout property
for BRANCH step 188, 418
for INVOKE step 179, 421
for LOOP step 201, 423
for MAP step 424
for REPEAT step 192, 193, 195, 426
for SEQUENCE step 429
529
Index
530
zooming in on 242
transient error, definition of 155, 408
trigger services, input signature requirements 139
triggers
disabled when copied 54
filter syntax restrictions 463
filters and relational operators 456
lexical operators 453
testing 294
used with adapter notifications 268
using standard relational operators 453
try sequence, in service retry 409
Tx End events
definition of 405
uses of 405
when generated 400
Tx Start events
definition of 405
uses of 405
when generated 400
type definitions
anonymous 249
complex types 249
simple types 248
U
Unicode, and Java source code 347
universal names
assigning to services 157
implicit vs explicit 158
local portion of name 157
namespace portion of name 157
removing from a service 159
unlocking elements
more than one 108
system locked 111
using Integration Server Administrator 110
using webMethods Developer 109
unresolved references, finding 68
unsignedByte content constraint 481
unsignedInt content constraint 482
unsignedLong content constraint 482
unSignedShort content constraint 482
update mode (jcode) 347
URL, invoking services from 366, 367
user account on webMethods Integration Server 22
Index
V
Validate input property 179, 236
definition 421
Validate output property 179, 236
definition 421
validatePipeline service 288
validating
See also validation
documents (IData objects) 287
from Java services 289
input/output for transformers 240
input/output via Input/Output tab 285
input/output via INVOKE step 286
pipeline via built-in services 288
pipeline, overview 288
service input/output 284, 285, 286
XML documents 288
validation
See also validating
allowing undeclared variables 280
applying constraints 279
benefits of 278
blueprints for 278
constraining facets 483
constraints, definition of 279
content constraints 473
definition of 278
errors 291, 488
exceptions 291, 502
input/output 284
overview 278
requiring variable existence 280
running out of memory 292
service input and output 284
stack overflow 292
types of 278
XML validation 288
validation errors and error codes 488
validation services
pub.schema:validate 287, 288
pub.schema:validatePipeline 288
value transformations, definition of 208
variables
adding to the pipeline 232
addressing in the pipeline 460
applying constraints 279
applying content constraints 472
applying content types 280
W
warnings
document (IData object) generation 507
flow service generation 507
IS schema generation 507
watt.server.invoke.maxRetryPeriod 156
watt.server.stats.pollTime property 403
webMethods Developer
main window 25
online help 42
starting 23
toolbar 30
531
Index
exceptions 502
IS schemas, overview 246
performing 288
structural constraints 246
Z
zooming
in a window 37
in on transformers 242
X
XML documents
and $xmldata 373
converting to IData objects 372
creating documents (IData objects) from 256
creating IS document types from 258
creating IS schemas from 251
passing to a service 372
posting via HTTP 376
testing services with 305
XML Namespace property, described 272
XML Schema definitions
creating documents (IData objects) from 256
creating IS document types from 258
creating IS schemas from 251
import mechanism 253
include mechanism 253
IS schema generation warnings 507
recursive complex types 262
redefine mechanism 253
referenced by other XML Schemas 253
XML validation
content constraints 246
creating IS schemas 251
definition of 288
errors 488
532